Changes between Version 2 and Version 3 of Video_Users_Guide


Ignore:
Timestamp:
Aug 15, 2011 4:54:43 AM (9 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Video_Users_Guide

    v2 v3  
    3737 
    3838 
     39[[BR]] 
     40 
    3941== Building with Video Support == 
    4042 
    41 === GNU Build System === 
     43=== Building with GNU Build System (for Mac OS X, Linux, etc.) === 
    4244 
    4345==== 1. Running aconfigure ==== 
     
    7577Once the build is successful, you will have '''pjsua''' executable containing video support. Additionally, you may want to build the [#vidgui GUI sample application] too. 
    7678 
    77 === Visual Studio === 
     79[[BR]] 
     80 
     81=== Building with Visual Studio === 
    7882 
    7983Visual Studio users will need to configure things manually as explained below. 
     
    101105Once the build is successful, you will have '''pjsua''' executable containing video support. Additionally, you may want to build the [#vidgui GUI sample application] too. 
    102106 
     107 
     108[[BR]] 
    103109 
    104110=== GUI Sample Application === #vidgui 
     
    131137 
    132138 
     139[[BR]] 
     140 
     141== Video API (pjsua-lib) == 
     142 
     143This 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. 
     144 
     145The Video API is classified into the following categories. 
     146 
     147=== Device enumeration API === 
     148 
     149The following API is available: 
     150 
     151{{{ 
     152/** 
     153 * Get the number of video devices installed in the system. 
     154 * 
     155 * @return              The number of devices. 
     156 */ 
     157PJ_DECL(unsigned) pjsua_vid_dev_count(void); 
     158 
     159/** 
     160 * Retrieve the video device info for the specified device index. 
     161 * 
     162 * @param id            The device index. 
     163 * @param vdi           Device info to be initialized. 
     164 * 
     165 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     166 */ 
     167PJ_DECL(pj_status_t) pjsua_vid_dev_get_info(pjmedia_vid_dev_index id, 
     168                                            pjmedia_vid_dev_info *vdi); 
     169 
     170/** 
     171 * Enum all video devices installed in the system. 
     172 * 
     173 * @param info          Array of info to be initialized. 
     174 * @param count         On input, specifies max elements in the array. 
     175 *                      On return, it contains actual number of elements 
     176 *                      that have been initialized. 
     177 * 
     178 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     179 */ 
     180PJ_DECL(pj_status_t) pjsua_vid_enum_devs(pjmedia_vid_dev_info info[], 
     181                                         unsigned *count); 
     182}}} 
     183 
     184In addition, the [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/group__video__device__reference.htm PJMEDIA videodev] also provides this API to detect change in device availability: 
     185 
     186{{{ 
     187/** 
     188 * Refresh the list of video devices installed in the system. This function 
     189 * will only refresh the list of videoo device so all active video streams will 
     190 * be unaffected. After refreshing the device list, application MUST make sure 
     191 * to update all index references to video devices (i.e. all variables of type 
     192 * pjmedia_vid_dev_index) before calling any function that accepts video device 
     193 * index as its parameter. 
     194 * 
     195 * @return              PJ_SUCCESS on successful operation or the appropriate 
     196 *                      error code. 
     197 */ 
     198PJ_DECL(pj_status_t) pjmedia_vid_dev_refresh(void); 
     199 
     200}}} 
     201 
     202=== Video preview API === 
     203 
     204The video preview API can be used to show the output of capture device to a video window: 
     205 
     206{{{ 
     207/** 
     208 * Parameters for starting video preview with pjsua_vid_preview_start(). 
     209 * Application should initialize this structure with 
     210 * pjsua_vid_preview_param_default(). 
     211 */ 
     212typedef struct pjsua_vid_preview_param 
     213{ 
     214    /** 
     215     * Device ID for the video renderer to be used for rendering the 
     216     * capture stream for preview. 
     217     */ 
     218    pjmedia_vid_dev_index       rend_id; 
     219} pjsua_vid_preview_param; 
     220 
     221 
     222/** 
     223 * Start video preview window for the specified capture device. 
     224 * 
     225 * @param id            The capture device ID where its preview will be 
     226 *                      started. 
     227 * @param prm           Optional video preview parameters. Specify NULL 
     228 *                      to use default values. 
     229 * 
     230 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     231 */ 
     232PJ_DECL(pj_status_t) pjsua_vid_preview_start(pjmedia_vid_dev_index id, 
     233                                             pjsua_vid_preview_param *prm); 
     234 
     235/** 
     236 * Get the preview window handle associated with the capture device, if any. 
     237 * 
     238 * @param id            The capture device ID. 
     239 * 
     240 * @return              The window ID of the preview window for the 
     241 *                      specified capture device ID, or NULL if preview 
     242 *                      does not exist. 
     243 */ 
     244PJ_DECL(pjsua_vid_win_id) pjsua_vid_preview_get_win(pjmedia_vid_dev_index id); 
     245 
     246/** 
     247 * Stop video preview. 
     248 * 
     249 * @param id            The capture device ID. 
     250 * 
     251 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     252 */ 
     253PJ_DECL(pj_status_t) pjsua_vid_preview_stop(pjmedia_vid_dev_index id); 
     254 
     255}}} 
     256 
     257 
     258=== Video Configuration === 
     259 
     260Video settings are mostly configured on {{{pjsua_acc_config}}} with the following fields: 
     261 
     262{{{ 
     263    /** 
     264     * Maximum number of simultaneous active video streams to be allowed 
     265     * for calls on this account. Setting this to zero will disable video 
     266     * in calls on this account, regardless of other video settings. 
     267     * 
     268     * Default: 1 
     269     */ 
     270    unsigned         max_video_cnt; 
     271 
     272    /** 
     273     * Specify whether incoming video should be shown to screen by default. 
     274     * This applies to incoming call (INVITE), incoming re-INVITE, and 
     275     * incoming UPDATE requests. 
     276     * 
     277     * Regardless of this setting, application can detect incoming video 
     278     * by implementing \a on_call_media_state() callback and enumerating 
     279     * the media stream(s) with #pjsua_call_get_info(). Once incoming 
     280     * video is recognised, application may retrieve the window associated 
     281     * with the incoming video and show or hide it with 
     282     * #pjsua_vid_win_set_show(). 
     283     * 
     284     * Default: PJ_FALSE 
     285     */ 
     286    pj_bool_t        vid_in_auto_show; 
     287 
     288    /** 
     289     * Specify whether outgoing video should be activated by default when 
     290     * making outgoing calls and/or when incoming video is detected. This 
     291     * applies to incoming and outgoing calls, incoming re-INVITE, and 
     292     * incoming UPDATE. If the setting is non-zero, outgoing video 
     293     * transmission will be started as soon as response to these requests 
     294     * is sent (or received). 
     295     * 
     296     * Regardless of the value of this setting, application can start and 
     297     * stop outgoing video transmission with #pjsua_call_set_vid_strm(). 
     298     * 
     299     * Default: PJ_FALSE 
     300     */ 
     301    pj_bool_t        vid_out_auto_transmit; 
     302 
     303    /** 
     304     * Specify the default capture device to be used by this account. If 
     305     * \a vid_out_auto_transmit is enabled, this device will be used for 
     306     * capturing video. 
     307     * 
     308     * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV 
     309     */ 
     310    pjmedia_vid_dev_index vid_cap_dev; 
     311 
     312    /** 
     313     * Specify the default rendering device to be used by this account. 
     314     * 
     315     * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV 
     316     */ 
     317    pjmedia_vid_dev_index vid_rend_dev; 
     318}}} 
     319 
     320 
     321=== Video Window API === 
     322 
     323A video window is a rectangular area in your monitor to display video content. The video content may come from remote stream, local camera (in case of preview), AVI playback, or any other video playback. Application mostly will be interested in the native handle of the video window so that it can embed it in its application window, however we also provide simple and commonly used API for manipulating the window. 
     324 
     325{{{ 
     326/** 
     327 * This structure describes video window info. 
     328 */ 
     329typedef struct pjsua_vid_win_info 
     330{ 
     331    /** 
     332     * Renderer device ID. 
     333     */ 
     334    pjmedia_vid_dev_index rdr_dev; 
     335 
     336    /** 
     337     * Native window handle. 
     338     */ 
     339    pjmedia_vid_dev_hwnd hwnd; 
     340 
     341    /** 
     342     * Window show status. The window is hidden if false. 
     343     */ 
     344    pj_bool_t   show; 
     345 
     346    /** 
     347     * Window position. 
     348     */ 
     349    pjmedia_coord pos; 
     350 
     351    /** 
     352     * Window size. 
     353     */ 
     354    pjmedia_rect_size size; 
     355 
     356} pjsua_vid_win_info; 
     357 
     358 
     359/** 
     360 * Enumerates all video windows. 
     361 * 
     362 * @param id            Array of window ID to be initialized. 
     363 * @param count         On input, specifies max elements in the array. 
     364 *                      On return, it contains actual number of elements 
     365 *                      that have been initialized. 
     366 * 
     367 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     368 */ 
     369PJ_DECL(pj_status_t) pjsua_vid_enum_wins(pjsua_vid_win_id wids[], 
     370                                         unsigned *count); 
     371 
     372 
     373/** 
     374 * Get window info. 
     375 * 
     376 * @param wid           The video window ID. 
     377 * @param wi            The video window info to be initialized. 
     378 * 
     379 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     380 */ 
     381PJ_DECL(pj_status_t) pjsua_vid_win_get_info(pjsua_vid_win_id wid, 
     382                                            pjsua_vid_win_info *wi); 
     383 
     384/** 
     385 * Show or hide window. 
     386 * 
     387 * @param wid           The video window ID. 
     388 * @param show          Set to PJ_TRUE to show the window, PJ_FALSE to 
     389 *                      hide the window. 
     390 * 
     391 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     392 */ 
     393PJ_DECL(pj_status_t) pjsua_vid_win_set_show(pjsua_vid_win_id wid, 
     394                                            pj_bool_t show); 
     395 
     396/** 
     397 * Set video window position. 
     398 * 
     399 * @param wid           The video window ID. 
     400 * @param pos           The window position. 
     401 * 
     402 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     403 */ 
     404PJ_DECL(pj_status_t) pjsua_vid_win_set_pos(pjsua_vid_win_id wid, 
     405                                           const pjmedia_coord *pos); 
     406 
     407/** 
     408 * Resize window. 
     409 * 
     410 * @param wid           The video window ID. 
     411 * @param size          The new window size. 
     412 * 
     413 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     414 */ 
     415PJ_DECL(pj_status_t) pjsua_vid_win_set_size(pjsua_vid_win_id wid, 
     416                                            const pjmedia_rect_size *size); 
     417 
     418}}} 
     419 
     420=== Video Codec API === 
     421 
     422API for managing video codecs: 
     423{{{ 
     424/** 
     425 * Enum all supported video codecs in the system. 
     426 * 
     427 * @param id            Array of ID to be initialized. 
     428 * @param count         On input, specifies max elements in the array. 
     429 *                      On return, it contains actual number of elements 
     430 *                      that have been initialized. 
     431 * 
     432 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     433 */ 
     434PJ_DECL(pj_status_t) pjsua_vid_enum_codecs( pjsua_codec_info id[], 
     435                                            unsigned *count ); 
     436 
     437 
     438/** 
     439 * Change video codec priority. 
     440 * 
     441 * @param codec_id      Codec ID, which is a string that uniquely identify 
     442 *                      the codec (such as "H263/90000"). Please see pjsua 
     443 *                      manual or pjmedia codec reference for details. 
     444 * @param priority      Codec priority, 0-255, where zero means to disable 
     445 *                      the codec. 
     446 * 
     447 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     448 */ 
     449PJ_DECL(pj_status_t) pjsua_vid_codec_set_priority( const pj_str_t *codec_id, 
     450                                                   pj_uint8_t priority ); 
     451 
     452 
     453/** 
     454 * Get video codec parameters. 
     455 * 
     456 * @param codec_id      Codec ID. 
     457 * @param param         Structure to receive video codec parameters. 
     458 * 
     459 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     460 */ 
     461PJ_DECL(pj_status_t) pjsua_vid_codec_get_param( 
     462                                        const pj_str_t *codec_id, 
     463                                        pjmedia_vid_codec_param *param); 
     464 
     465 
     466/** 
     467 * Set video codec parameters. 
     468 * 
     469 * @param codec_id      Codec ID. 
     470 * @param param         Codec parameter to set. Set to NULL to reset 
     471 *                      codec parameter to library default settings. 
     472 * 
     473 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     474 */ 
     475PJ_DECL(pj_status_t) pjsua_vid_codec_set_param(  
     476                                        const pj_str_t *codec_id, 
     477                                        const pjmedia_vid_codec_param *param); 
     478 
     479}}} 
    133480 
    134481