Changes between Version 4 and Version 5 of Video_Users_Guide

Timestamp:

Aug 15, 2011 6:44:00 AM (13 years ago)

Author:

bennylp

Comment:

--

Video_Users_Guide

@@ -139 +139 @@
 [[BR]]
 
-== Video API (pjsua-lib) ==
-
-This section explains and lists the Video API as it was available when this document is written. For a more up to date lists, please see [http://www.pjsip.org/docs/latest-2/pjsip/docs/html/group__PJSUA__LIB__VIDEO.htm Video API reference documentation]. Please see this page for detailed reference of the API.
+== Using Video API (pjsua-lib) ==
+
+This section provides several sample scenarios of using video in your application. Please see [#vidref Video API Reference] section for a more complete documentation about the Video API.
+
+=== Enabling video ===
+
+By default, video is enabled in {{{pjsua_acc_config}}}, via {{{max_video_cnt}}} setting.
+
+=== 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.
+
+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:
+
+{{{
+pjsua_acc_config cfg;
+
+pjsua_acc_config_default(&cfg);
+cfg.wid_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:
+ {{{
+ int vid_idx;
+ pjsua_vid_win_id wid;
+
+ vid_idx = pjsua_call_get_vid_stream_idx(call_id);
+ if (vid_idx >= 0) {
+     pjsua_call_info ci;
+
+     pjsua_call_get_info(call_id, &ci);
+     wid = ci.media[vid_idx].stream.vid.win_in;
+ }
+ }}}
+ 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'''.
+
+
+[[BR]]
+
+== Video API Reference (pjsua-lib) == #vidref
+
+This section explains and lists the Video API as it was available when this document is written. For a richer and more up to date list, please see [http://www.pjsip.org/docs/latest-2/pjsip/docs/html/group__PJSUA__LIB__VIDEO.htm Video API reference doxygen documentation]. 
 
 The Video API is classified into the following categories.