Changes between Version 5 and Version 6 of Video_Users_Guide

Timestamp:

Aug 15, 2011 8:30:07 AM (13 years ago)

Author:

bennylp

Comment:

--

Video_Users_Guide

@@ -145 +145 @@
 === Enabling video ===
 
-By default, video is enabled in {{{pjsua_acc_config}}}, via {{{max_video_cnt}}} setting.
+By default, video is enabled in '''{{{pjsua_acc_config}}}''', via '''{{{max_video_cnt}}}''' setting. The subsequent discussions assume that video is enabled on the account.
 
 === Incoming video display ===
 
-As long as video is enabled in the account config (see above), incoming video by default will be accepted as long as we have matching codec for it. However, this does not necessarily mean that the video will be displayed automatically to the screen, nor that we will automatically transmit outgoing video because of that, as there will be additional settings to control these. Outgoing video behavior will be explained in the following section.
+As long as video is enabled in the account config (see above), incoming video by default will be accepted as long as we have matching codec for it. However, this does not necessarily mean that the video will be displayed automatically to the screen, nor that outgoing video will be transmitted automatically, as there will be separate settings for these. Outgoing video behavior will be explained in the next section.
 
 By default, incoming video '''is not''' displayed automatically, since the app may want to seek user approval first. Use the following code to change this behavior on per account basis:
@@ -157 +157 @@
 
 pjsua_acc_config_default(&cfg);
-cfg.wid_in_auto_show = PJ_TRUE;
+cfg.vid_in_auto_show = PJ_TRUE;
 }}}
 
 Regardless of the setting above, you can use the following steps to show or hide the display incoming video:
 
- 1. Use {{{pjsua_call_get_vid_stream_idx()}}} or enumerate the call's media stream to find the media index of the default video. If there are multiple video streams in a call, the default video is the first active video media in the call.
- 1. Locate the media information of the specified stream index in the {{{pjsua_call_info}}}, and acquire the window ID associated with the remote video. Sample code:
+ 1. Use '''{{{pjsua_call_get_vid_stream_idx()}}}''' or enumerate the call's media stream to find the media index of the default video. If there are multiple video streams in a call, the default video is the first active video media in the call.
+ 1. Locate the media information of the specified stream index in the '''{{{pjsua_call_info}}}''', and acquire the window ID associated with the remote video. Sample code:
  {{{
  int vid_idx;
@@ -176 +176 @@
  }
  }}}
- 1. Using the video window ID, you may retrieve the associated native video handle with {{{pjsua_vid_win_get_info()}}} and then show or hide the video window using native API, or use {{{pjsua_vid_win_set_show()}}} to show/hide the window using PJSUA API.
-
-Controlling the video window above will not cause any re-INVITE or UPDATE to be sent to remote, since the operation occurs locally. However, if you wish, you may alter the incoming video stream with {{{pjsua_call_set_vid_strm()}}} API, and this '''will''' cause re-INVITE or UPDATE to be sent to negotiate the new SDP. The relevant operation to control incoming video with {{{pjsua_call_set_vid_strm()}}} are:
- - PJSUA_CALL_VID_STRM_CHANGE_DIR: change the media direction (e.g. to "sendonly", or even "inactive")
- - PJSUA_CALL_VID_STRM_REMOVE: remove the media stream altogether by settings its port to zero
- - PJSUA_CALL_VID_STRM_ADD: add new video media stream
-
-Since {{{pjsua_call_set_vid_strm()}}} will result in renegotiation of the SDP in a re-INVITE or UPDATE transaction, the result of this operation will not be available immediately. Application can monitor the status by implementing '''on_call_media_state()''' callback and enumerate the media stream status with '''pjsua_call_info'''.
+ 1. Using the video window ID, you may retrieve the associated native video handle with '''{{{pjsua_vid_win_get_info()}}}''' and then show or hide the video window using native API, or use '''{{{pjsua_vid_win_set_show()}}}''' to show/hide the window using PJSUA API. See [#wwin Working with Window] section below for information on manipulating video windows.
+
+Controlling the video window above will not cause any re-INVITE or UPDATE to be sent to remote, since the operation occurs locally. However, if you wish, you may alter the incoming video stream with '''{{{pjsua_call_set_vid_strm()}}}''' API, and this '''will''' cause re-INVITE or UPDATE to be sent to negotiate the new SDP. The relevant operation to control incoming video with '''{{{pjsua_call_set_vid_strm()}}}''' are:
+ - ''PJSUA_CALL_VID_STRM_CHANGE_DIR'': change the media direction (e.g. to "sendonly", or even "inactive")
+ - ''PJSUA_CALL_VID_STRM_REMOVE'': remove the media stream altogether by settings its port to zero
+ - ''PJSUA_CALL_VID_STRM_ADD'': add new video media stream
+
+Since '''{{{pjsua_call_set_vid_strm()}}}''' will result in renegotiation of the SDP in a re-INVITE or UPDATE transaction, the result of this operation will not be available immediately. Application can monitor the status by implementing '''{{{on_call_media_state()}}}''' callback and enumerate the media stream status with '''pjsua_call_info'''.
+
+
+=== Outgoing Video Transmission ===
+
+Outgoing video transmission is independent from the incoming video transmission; each can be operated separately. Even though video by default is enabled on the account, outgoing video transmission '''is not started by default'''. Not even when incoming offer contains video support. This behavior is controlled by '''{{{pjsua_acc_config.vid_out_auto_transmit}}}''' setting, which default to ''PJ_FALSE''. Setting this to ''PJ_TRUE''' will cause video transmission to be started automatically on each outgoing calls and on incoming calls that indicates video support in its offer. However, it is more flexible and appropriate to leave this setting at PJ_FALSE, and add video later during the call by using '''{{{pjsua_call_set_vid_strm()}}}''' API, as will be explained shortly.
+
+The default capture device that is used by an account is configured in '''{{{pjsua_acc_config.vid_cap_dev}}}''' setting. It is more convenient to set the "correct" device here rather than having to set it in every other API calls later.
+
+Application uses '''{{{pjsua_call_set_vid_strm()}}}''' API to control video media on a call. The following ''op_code'' can be used on the API to control the video media:
+ - ''PJSUA_CALL_VID_STRM_ADD'': add a new video stream
+ - ''PJSUA_CALL_VID_STRM_REMOVE'': remove video stream (set port to zero)
+ - ''PJSUA_CALL_VID_STRM_CHANGE_DIR'': change direction or deactivate (i.e. set direction to "inactive")
+ - ''PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV'': change capture device
+ - ''PJSUA_CALL_VID_STRM_START_TRANSMIT'': start previously stopped transmission
+ - ''PJSUA_CALL_VID_STRM_STOP_TRANSMIT'': stop transmission
+
+Some of the video operations above require re-INVITE or UPDATE to be sent, hence the result will not be available immediately. In that case, application can implement '''{{{on_call_media_state()}}}''' callback and inspect the resulting negotiation by looking at the '''{{{pjsua_call_info}}}'''. Please see [#vcm Video Call Manipulation] in the API reference section below for more information about the operations above.
+
+
+=== Working with Video Window === #wwin
+
+Video Window represents all window objects on the screen that the library creates. The video window can display incoming video, preview, and/or other video playbacks.
+
+Application may retrieve video windows from the following places:
+ - for calls, the video window of incoming video stream is contained in the media stream inside '''{{{pjsua_call_info}}}''' structure.
+ - preview window associated with a capture device can be queried with '''{{{pjsua_vid_preview_get_win()}}}'''.
+ - for all other purposes, application may enumerate all video windows with '''{{{pjsua_vid_enum_wins()}}}'''.
+
+Application retrieves '''{{{pjsua_vid_win_info}}}''' with '''{{{pjsua_vid_win_get_info()}}}'''. The one window property that most applications will be interested with is the native window handle of the video. The native video handle is contained by '''{{{pjmedia_vid_dev_hwnd}}}''' structure inside '''{{{pjsua_vid_win_info}}}'''. Application can use the native handle to embed the video window into application's GUI structure. Alternatively, the library also provides few simple and most commonly used API to operate the window, such as {{{pjsua_vid_win_set_show()}}}, {{{pjsua_vid_win_set_size()}}}, etc., however the availability of these APIs are not guaranteed since it depends on the underlying backend device.
 
 
@@ -378 +407 @@
 typedef enum pjsua_call_vid_strm_op
 {
+    /**
+     * No operation.
+     */
+    PJSUA_CALL_VID_STRM_NO_OP,
+
     /**
      * Add a new video stream. This will add a new m=video line to