==================
映像の送受信と描画
==================

映像を送受信する
================

カメラの映像を取得する
----------------------

.. キャプチャラーの意味を説明する

カメラの映像を取得するキャプチャラー (``org.webrtc.CameraVideoCapturer``) は `jp.shiguredo.sora.sdk.camera.CameraCapturerFactory`_ を呼ぶと取得できます。

`create()`_ の定義は次の通りです:

.. code-block:: kotlin

  fun create(context: android.content.Context,
             fixedResolution: Boolean = false,
             frontFacingFirst: Boolean = true) : org.webrtc.CameraVideoCapturer? 

- ``context``: アプリケーションコンテキスト。 ``Activity`` オブジェクトを渡します。
- ``fixedResolution``: ``true`` であれば解像度の維持を優先します。 ``false`` であればフレームレートの維持を優先します。デフォルトは ``false`` です。
- ``frontFacingFirst``: ``true`` であれば前面カメラを優先します。 ``false`` であれば背面カメラを優先します。デフォルトは ``true`` です。

.. _create(): https://sora-android-sdk.shiguredo.jp/apidoc/sora-android-sdk/jp.shiguredo.sora.sdk.camera/-camera-capturer-factory/-companion/create
.. _jp.shiguredo.sora.sdk.camera.CameraCapturerFactory: https://sora-android-sdk.shiguredo.jp/apidoc/sora-android-sdk/jp.shiguredo.sora.sdk.camera/-camera-capturer-factory/index.html

使用例
^^^^^^

.. code-block:: kotlin

   class MainActivity : AppCompatActivity() {

     fun start() {
       capturer = CameraCapturerFactory.create(this)
       ...
     }

   }


映像を描画する
==============

Sora Android SDK は基本的に libwebrtc の API を隠蔽していますが、映像の描画には直接 libwebrtc の API を使う必要があります。


UI コンポーネント
-----------------

映像を描画する UI コンポーネントは ``org.webrtc.SurfaceViewRenderer`` です。
``SurfaceViewRenderer`` は ``android.view.SurfaceView`` のサブクラスであり、 OpenGL ES を利用して映像を描画します。


.. _ui_layout:

レイアウト
----------

``SurfaceViewRenderer`` は一般的なレイアウトと同様に XML ファイルでレイアウトを定義できます。

次に例を示します:

.. code-block:: xml

   <LinearLayout
       android:id="@+id/renderers"
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       android:orientation="vertical"
       android:padding="20dp">
  
       <org.webrtc.SurfaceViewRenderer
           android:id="@+id/localRenderer"
           android:layout_width="match_parent"
           android:layout_height="300dp"/>
  
       <org.webrtc.SurfaceViewRenderer
           android:id="@+id/remoteRenderer"
           android:layout_width="match_parent"
           android:layout_height="300dp" />
   </LinearLayout>

初期化と終了処理
----------------

``SurfaceViewRenderer`` で映像を描画する際は、明示的な初期化と終了処理を行う必要があります。
映像の描画を行う前に ``init()`` を呼び出して初期化し、 ``SurfaceViewRenderer`` を使い終えたら ``release()`` を呼び出して終了処理を行います。
終了処理を忘れるとリソースがリークする原因になります。

``init()`` は EGL の API である ``android.opengl.EGLContext`` を引数に取ります。
``EGLContext`` は ``org.webrtc.EglBase`` のプロパティであり、他にも様々な箇所で使います。

``EglBase`` は EGL のレンダリングコンテキストを保持するオブジェクトです。
こちらも使い終えたら ``release()`` で終了処理を行う必要があります。

一般的には、アクティビティの生成時に ``EglBase`` の生成と ``SurfaceViewRenderer`` の初期化を行い、アクティビティの終了時に両方の終了処理を行うとよいでしょう。
次に例を示します:

.. code-block:: kotlin

   class MyActivity : AppCompatActivity() {

       private val egl: EglBase? = null

       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
           egl = EglBase.create()
           // その他の初期化
       }

       // UIの組み立てが終わった直後にこのメソッドを呼ぶようにする
       fun initRenderers() {
           // localRenderer, remoteRenderer は XML ファイルで定義済み
           localRenderer.init(egl.eglContext, null)
           remoteRenderer.init(egl.eglContext, null)
       }

       // このメソッドを最後に必ず呼ぶようにする
       fun releaseRenderers() {
           localRenderer.release()
           remoteRenderer.release()
           egl.release()
       }
   }



動画の左右を反転する
--------------------

``setMirror()`` を呼ぶと動画の左右を反転させることができます。

例
^^

.. code-block:: kotlin

  localRenderer.setMirror(true)


キャプチャーの操作
==================

キャプチャーを開始する
----------------------

映像のキャプチャーを開始するには ``startCapture()`` を呼びます。


キャプチャーを停止する
----------------------

キャプチャーを停止するには ``stopCapture()`` を呼びます。


キャプチャーのフォーマットを変更する
------------------------------------

``changeCaptureFormat()`` を使うと、キャプチャーした映像のサイズとフレームレートを変更できます。