Changes between Version 8 and Version 9 of Video_Users_Guide


Ignore:
Timestamp:
Aug 15, 2011 8:49:33 AM (13 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Video_Users_Guide

    v8 v9  
    165165Regardless of the setting above, you can use the following steps to show or hide the display incoming video: 
    166166 
    167  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. 
    168  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: 
     167 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. 
     168 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: 
    169169 {{{ 
    170170 int vid_idx; 
     
    179179 } 
    180180 }}} 
    181  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. 
     181 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. 
    182182 
    183183==== Controlling Incoming Video Stream ==== 
    184184 
    185 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: 
     185Controlling 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: 
    186186 - ''PJSUA_CALL_VID_STRM_CHANGE_DIR'': change the media direction (e.g. to "sendonly", or even "inactive") 
    187187 - ''PJSUA_CALL_VID_STRM_REMOVE'': remove the media stream altogether by settings its port to zero 
    188188 - ''PJSUA_CALL_VID_STRM_ADD'': add new video media stream 
    189189 
    190 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'''. 
     190Since {{{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. 
    191191 
    192192[[BR]] 
     
    194194=== Outgoing Video Transmission === 
    195195 
    196 Outgoing video transmission is independent from the incoming video transmission; each can be operated separately. Even though video is enabled by default 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. 
     196Outgoing video transmission is independent from the incoming video transmission; each can be operated separately. Even though video is enabled by default 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. 
    197197 
    198198==== Default Capture Device ==== 
    199199 
    200 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. 
     200The 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. 
    201201 
    202202==== Controlling Video Stream ==== 
    203203 
    204 Application uses '''{{{pjsua_call_set_vid_strm()}}}''' API to control video stream on a call. The following ''op_code'' can be used on the API to control the video media: 
     204Application uses {{{pjsua_call_set_vid_strm()}}} API to control video stream on a call. The following ''op_code'' can be used on the API to control the video media: 
    205205 - ''PJSUA_CALL_VID_STRM_ADD'': add a new video stream 
    206206 - ''PJSUA_CALL_VID_STRM_REMOVE'': remove video stream (set port to zero) 
     
    210210 - ''PJSUA_CALL_VID_STRM_STOP_TRANSMIT'': stop transmission 
    211211 
    212 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. 
     212Some 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. 
    213213 
    214214[[BR]] 
     
    219219 
    220220Application may retrieve video windows from the following places: 
    221  - for calls, the video window of incoming video stream is contained in the media stream inside '''{{{pjsua_call_info}}}''' structure. 
    222  - preview window associated with a capture device can be queried with '''{{{pjsua_vid_preview_get_win()}}}'''. 
    223  - for all other purposes, application may enumerate all video windows with '''{{{pjsua_vid_enum_wins()}}}'''. 
    224  
    225 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. 
     221 - for calls, the video window of incoming video stream is contained in the media stream inside {{{pjsua_call_info}}} structure. 
     222 - preview window associated with a capture device can be queried with {{{pjsua_vid_preview_get_win()}}}. 
     223 - for all other purposes, application may enumerate all video windows with {{{pjsua_vid_enum_wins()}}}. 
     224 
     225Application 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. 
    226226 
    227227