Changes between Version 5 and Version 6 of Video_Users_Guide


Ignore:
Timestamp:
Aug 15, 2011 8:30:07 AM (8 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Video_Users_Guide

    v5 v6  
    145145=== Enabling video === 
    146146 
    147 By default, video is enabled in {{{pjsua_acc_config}}}, via {{{max_video_cnt}}} setting. 
     147By default, video is enabled in '''{{{pjsua_acc_config}}}''', via '''{{{max_video_cnt}}}''' setting. The subsequent discussions assume that video is enabled on the account. 
    148148 
    149149=== Incoming video display === 
    150150 
    151 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. 
     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 outgoing video will be transmitted automatically, as there will be separate settings for these. Outgoing video behavior will be explained in the next section. 
    152152 
    153153By 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: 
     
    157157 
    158158pjsua_acc_config_default(&cfg); 
    159 cfg.wid_in_auto_show = PJ_TRUE; 
     159cfg.vid_in_auto_show = PJ_TRUE; 
    160160}}} 
    161161 
    162162Regardless of the setting above, you can use the following steps to show or hide the display incoming video: 
    163163 
    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: 
     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: 
    166166 {{{ 
    167167 int vid_idx; 
     
    176176 } 
    177177 }}} 
    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  
    180 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: 
    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  
    185 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'''. 
     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. See [#wwin Working with Window] section below for information on manipulating video windows. 
     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=== Outgoing Video Transmission === 
     189 
     190Outgoing 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. 
     191 
     192The 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. 
     193 
     194Application 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: 
     195 - ''PJSUA_CALL_VID_STRM_ADD'': add a new video stream 
     196 - ''PJSUA_CALL_VID_STRM_REMOVE'': remove video stream (set port to zero) 
     197 - ''PJSUA_CALL_VID_STRM_CHANGE_DIR'': change direction or deactivate (i.e. set direction to "inactive") 
     198 - ''PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV'': change capture device 
     199 - ''PJSUA_CALL_VID_STRM_START_TRANSMIT'': start previously stopped transmission 
     200 - ''PJSUA_CALL_VID_STRM_STOP_TRANSMIT'': stop transmission 
     201 
     202Some 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. 
     203 
     204 
     205=== Working with Video Window === #wwin 
     206 
     207Video 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. 
     208 
     209Application may retrieve video windows from the following places: 
     210 - for calls, the video window of incoming video stream is contained in the media stream inside '''{{{pjsua_call_info}}}''' structure. 
     211 - preview window associated with a capture device can be queried with '''{{{pjsua_vid_preview_get_win()}}}'''. 
     212 - for all other purposes, application may enumerate all video windows with '''{{{pjsua_vid_enum_wins()}}}'''. 
     213 
     214Application 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. 
    186215 
    187216 
     
    378407typedef enum pjsua_call_vid_strm_op 
    379408{ 
     409    /** 
     410     * No operation. 
     411     */ 
     412    PJSUA_CALL_VID_STRM_NO_OP, 
     413 
    380414    /** 
    381415     * Add a new video stream. This will add a new m=video line to