Changes between Version 4 and Version 5 of Video_Users_Guide


Ignore:
Timestamp:
Aug 15, 2011 6:44:00 AM (13 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Video_Users_Guide

    v4 v5  
    139139[[BR]] 
    140140 
    141 == Video API (pjsua-lib) == 
    142  
    143 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. 
     141== Using Video API (pjsua-lib) == 
     142 
     143This 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. 
     144 
     145=== Enabling video === 
     146 
     147By default, video is enabled in {{{pjsua_acc_config}}}, via {{{max_video_cnt}}} setting. 
     148 
     149=== Incoming video display === 
     150 
     151As 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. 
     152 
     153By 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: 
     154 
     155{{{ 
     156pjsua_acc_config cfg; 
     157 
     158pjsua_acc_config_default(&cfg); 
     159cfg.wid_in_auto_show = PJ_TRUE; 
     160}}} 
     161 
     162Regardless of the setting above, you can use the following steps to show or hide the display incoming video: 
     163 
     164 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. 
     165 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: 
     166 {{{ 
     167 int vid_idx; 
     168 pjsua_vid_win_id wid; 
     169 
     170 vid_idx = pjsua_call_get_vid_stream_idx(call_id); 
     171 if (vid_idx >= 0) { 
     172     pjsua_call_info ci; 
     173 
     174     pjsua_call_get_info(call_id, &ci); 
     175     wid = ci.media[vid_idx].stream.vid.win_in; 
     176 } 
     177 }}} 
     178 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. 
     179 
     180Controlling 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: 
     181 - PJSUA_CALL_VID_STRM_CHANGE_DIR: change the media direction (e.g. to "sendonly", or even "inactive") 
     182 - PJSUA_CALL_VID_STRM_REMOVE: remove the media stream altogether by settings its port to zero 
     183 - PJSUA_CALL_VID_STRM_ADD: add new video media stream 
     184 
     185Since {{{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'''. 
     186 
     187 
     188[[BR]] 
     189 
     190== Video API Reference (pjsua-lib) == #vidref 
     191 
     192This 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].  
    144193 
    145194The Video API is classified into the following categories.