Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjmedia / include / pjmedia-videodev / videodev.h
1 /* $Id$ */
2 /*
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation; either version 2 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18  */
19 #ifndef __PJMEDIA_VIDEODEV_VIDEODEV_H__
20 #define __PJMEDIA_VIDEODEV_VIDEODEV_H__
21
22 /**
23  * @file videodev.h
24  * @brief Video device API.
25  */
26 #include <pjmedia-videodev/config.h>
27 #include <pjmedia-videodev/errno.h>
28 #include <pjmedia/event.h>
29 #include <pjmedia/frame.h>
30 #include <pjmedia/format.h>
31 #include <pj/pool.h>
32
33
34 PJ_BEGIN_DECL
35
36 /**
37  * @defgroup video_device_reference Video Device API Reference
38  * @ingroup video_device_api
39  * @brief API Reference
40  * @{
41  */
42  
43 /**
44  * Type for device index.
45  */
46 typedef pj_int32_t pjmedia_vid_dev_index;
47
48 /**
49  * Enumeration of window handle type.
50  */
51 typedef enum pjmedia_vid_dev_hwnd_type
52 {
53     /**
54      * Type none.
55      */
56     PJMEDIA_VID_DEV_HWND_TYPE_NONE,
57
58     /**
59      * Native window handle on Windows.
60      */
61     PJMEDIA_VID_DEV_HWND_TYPE_WINDOWS
62
63 } pjmedia_vid_dev_hwnd_type;
64
65 /**
66  * Type for window handle.
67  */
68 typedef struct pjmedia_vid_dev_hwnd
69 {
70     /**
71      * The window handle type.
72      */
73     pjmedia_vid_dev_hwnd_type type;
74
75     /**
76      * The window handle.
77      */
78     union
79     {
80         struct {
81             void    *hwnd;      /**< HWND       */
82         } win;
83         struct {
84             void    *window;    /**< Window     */
85             void    *display;   /**< Display    */
86         } x11;
87         struct {
88             void    *window;    /**< Window     */
89         } cocoa;
90         struct {
91             void    *window;    /**< Window     */
92         } ios;
93         void        *window;
94     } info;
95
96 } pjmedia_vid_dev_hwnd;
97
98 /**
99  * Parameter for switching device with PJMEDIA_VID_DEV_CAP_SWITCH capability.
100  * Initialize this with pjmedia_vid_dev_switch_param_default()
101  */
102 typedef struct pjmedia_vid_dev_switch_param
103 {
104     /**
105      * Target device ID to switch to. Once the switching is successful, the
106      * video stream will use this device and the old device will be closed.
107      */
108     pjmedia_vid_dev_index target_id;
109
110 } pjmedia_vid_dev_switch_param;
111
112
113 /**
114  * Enumeration of window flags.
115  */
116 typedef enum pjmedia_vid_dev_wnd_flag
117 {
118     /**
119      * Window with border.
120      */
121     PJMEDIA_VID_DEV_WND_BORDER = 1,
122
123     /**
124      * Window can be resized.
125      */
126     PJMEDIA_VID_DEV_WND_RESIZABLE = 2
127
128 } pjmedia_vid_dev_wnd_flag;
129
130
131 /**
132  * Device index constants.
133  */
134 enum
135 {
136     /**
137      * Constant to denote default capture device
138      */
139     PJMEDIA_VID_DEFAULT_CAPTURE_DEV = -1,
140
141     /**
142      * Constant to denote default render device
143      */
144     PJMEDIA_VID_DEFAULT_RENDER_DEV = -2,
145
146     /**
147      * Constant to denote invalid device index.
148      */
149     PJMEDIA_VID_INVALID_DEV = -3
150 };
151
152
153 /**
154  * This enumeration identifies various video device capabilities. These video
155  * capabilities indicates what features are supported by the underlying
156  * video device implementation.
157  *
158  * Applications get these capabilities in the #pjmedia_vid_dev_info structure.
159  *
160  * Application can also set the specific features/capabilities when opening
161  * the video stream by setting the \a flags member of #pjmedia_vid_dev_param
162  * structure.
163  *
164  * Once video stream is running, application can also retrieve or set some
165  * specific video capability, by using #pjmedia_vid_dev_stream_get_cap() and
166  * #pjmedia_vid_dev_stream_set_cap() and specifying the desired capability. The
167  * value of the capability is specified as pointer, and application needs to
168  * supply the pointer with the correct value, according to the documentation
169  * of each of the capability.
170  */
171 typedef enum pjmedia_vid_dev_cap
172 {
173     /**
174      * Support for video formats. The value of this capability
175      * is represented by #pjmedia_format structure.
176      */
177     PJMEDIA_VID_DEV_CAP_FORMAT = 1,
178
179     /**
180      * Support for video input scaling
181      */
182     PJMEDIA_VID_DEV_CAP_INPUT_SCALE = 2,
183
184     /**
185      * Support for returning the native window handle of the video window.
186      * For renderer, this means the window handle of the renderer window,
187      * while for capture, this means the window handle of the native preview,
188      * only if the device supports  PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW
189      * capability.
190      *
191      * The value of this capability is pointer to pjmedia_vid_dev_hwnd
192      * structure.
193      */
194     PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW = 4,
195
196     /**
197      * Support for resizing video output. This capability SHOULD be 
198      * implemented by renderer, to alter the video output dimension on the fly.
199      * Value is pjmedia_rect_size. 
200      */
201     PJMEDIA_VID_DEV_CAP_OUTPUT_RESIZE = 8,
202
203     /**
204      * Support for setting the video window's position.
205      * Value is pjmedia_coord specifying the window's new coordinate.
206      */
207     PJMEDIA_VID_DEV_CAP_OUTPUT_POSITION = 16,
208
209     /**
210      * Support for setting the video output's visibility.
211      * The value of this capability is a pj_bool_t containing boolean
212      * PJ_TRUE or PJ_FALSE.
213      */
214     PJMEDIA_VID_DEV_CAP_OUTPUT_HIDE = 32,
215
216     /**
217      * Support for native preview capability in capture devices. Value is
218      * pj_bool_t. With native preview, capture device can be instructed to
219      * show or hide a preview window showing video directly from the camera
220      * by setting this capability to PJ_TRUE or PJ_FALSE. Once the preview
221      * is started, application may use PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW
222      * capability to query the vidow window.
223      *
224      * The value of this capability is a pj_bool_t containing boolean
225      * PJ_TRUE or PJ_FALSE.
226      */
227     PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW = 64,
228
229     /**
230      * Support for changing video orientation in renderer and querying
231      * video orientation info in capture. Changing video orientation in
232      * a renderer will potentially affect the size of render window,
233      * i.e: width and height swap. When a capture device supports this
234      * capability, it will generate event PJMEDIA_EVENT_ORIENT_CHANGED
235      * (see #pjmedia_event) everytime the capture orientation is changed.
236      *
237      * The value of this capability is pjmedia_orient.
238      */
239     PJMEDIA_VID_DEV_CAP_ORIENTATION = 128,
240
241     /**
242      * Support for fast switching to another device. A video stream with this
243      * capability allows replacing of its underlying device with another
244      * device, saving the user from opening a new video stream and gets a much
245      * faster and smoother switching action.
246      *
247      * Note that even when this capability is supported by a device, it may
248      * not be able to switch to arbitrary device. Application must always
249      * check the return value of the operation to verify that switching has
250      * occurred.
251      *
252      * This capability is currently write-only (i.e. set-only).
253      *
254      * The value of this capability is pointer to pjmedia_vid_dev_switch_param
255      * structure.
256      */
257     PJMEDIA_VID_DEV_CAP_SWITCH = 256,
258
259     /**
260      * Support for setting the output video window's flags.
261      * The value of this capability is a bitmask combination of
262      * #pjmedia_vid_dev_wnd_flag.
263      */
264     PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW_FLAGS = 512,
265
266     /**
267      * End of standard capability
268      */
269     PJMEDIA_VID_DEV_CAP_MAX = 16384
270
271 } pjmedia_vid_dev_cap;
272
273 /**
274  * Device information structure returned by #pjmedia_vid_dev_get_info().
275  */
276 typedef struct pjmedia_vid_dev_info
277 {
278     /** The device ID */
279     pjmedia_vid_dev_index id;
280
281     /** The device name */
282     char name[64];
283
284     /** The underlying driver name */
285     char driver[32];
286
287     /** 
288      * The supported direction of the video device, i.e. whether it supports 
289      * capture only, render only, or both.
290      */
291     pjmedia_dir dir;
292
293     /**
294      * Specify whether the device supports callback. Devices that implement
295      * "active interface" will actively call the callbacks to give or ask for
296      * video frames. If the device doesn't support callback, application
297      * must actively request or give video frames from/to the device by using
298      * pjmedia_vid_dev_stream_get_frame()/pjmedia_vid_dev_stream_put_frame().
299      */
300     pj_bool_t has_callback;
301
302     /** Device capabilities, as bitmask combination of #pjmedia_vid_dev_cap */
303     unsigned caps;
304
305     /** Number of video formats supported by this device */
306     unsigned fmt_cnt;
307
308     /** 
309      * Array of supported video formats. Some fields in each supported video
310      * format may be set to zero or of "unknown" value, to indicate that the
311      * value is unknown or should be ignored. When these value are not set
312      * to zero, it indicates that the exact format combination is being used. 
313      */
314     pjmedia_format fmt[PJMEDIA_VID_DEV_INFO_FMT_CNT];
315
316 } pjmedia_vid_dev_info;
317
318
319 /** Forward declaration for pjmedia_vid_dev_stream */
320 typedef struct pjmedia_vid_dev_stream pjmedia_vid_dev_stream;
321
322 typedef struct pjmedia_vid_dev_cb
323 {
324     /**
325     * This callback is called by capturer stream when it has captured the
326     * whole packet worth of video samples.
327     *
328     * @param stream        The video stream.
329     * @param user_data     User data associated with the stream.
330     * @param frame         Captured frame.
331     *
332     * @return              Returning non-PJ_SUCCESS will cause the video
333     *                      stream to stop
334     */
335     pj_status_t (*capture_cb)(pjmedia_vid_dev_stream *stream,
336                               void *user_data,
337                               pjmedia_frame *frame);
338
339     /**
340     * This callback is called by renderer stream when it needs additional
341     * data to be rendered by the device. Application must fill in the whole
342     * of output buffer with video samples.
343     *
344     * The frame argument contains the following values:
345     *  - timestamp         Rendering timestamp, in samples.
346     *  - buf               Buffer to be filled out by application.
347     *  - size              The size requested in bytes, which will be equal
348     *                      to the size of one whole packet.
349     *
350     * @param stream        The video stream.
351     * @param user_data     User data associated with the stream.
352     * @param frame         Video frame, which buffer is to be filled in by
353     *                      the application.
354     *
355     * @return              Returning non-PJ_SUCCESS will cause the video 
356     *                      stream to stop
357     */
358     pj_status_t (*render_cb)(pjmedia_vid_dev_stream *stream,
359                              void *user_data,
360                              pjmedia_frame *frame);
361
362 } pjmedia_vid_dev_cb;
363
364
365 /**
366  * This structure specifies the parameters to open the video stream.
367  */
368 typedef struct pjmedia_vid_dev_param
369 {
370     /**
371      * The video direction. This setting is mandatory.
372      */
373     pjmedia_dir dir;
374
375     /**
376      * The video capture device ID. This setting is mandatory if the video
377      * direction includes input/capture direction.
378      */
379     pjmedia_vid_dev_index cap_id;
380
381     /**
382      * The video render device ID. This setting is mandatory if the video
383      * direction includes output/render direction.
384      */
385     pjmedia_vid_dev_index rend_id;
386
387     /** 
388      * Video clock rate. This setting is mandatory if the video
389      * direction includes input/capture direction
390      */
391     unsigned clock_rate;
392
393     /**
394      * Video frame rate. This setting is mandatory if the video
395      * direction includes input/capture direction
396      */
397 //    pjmedia_ratio frame_rate;
398
399     /**
400      * This flags specifies which of the optional settings are valid in this
401      * structure. The flags is bitmask combination of pjmedia_vid_dev_cap.
402      */
403     unsigned flags;
404
405     /**
406      * Set the video format. This setting is mandatory.
407      */
408     pjmedia_format fmt;
409
410     /**
411      * Window for the renderer to display the video. This setting is optional,
412      * and will only be used if PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW is set in 
413      * the flags.
414      */
415     pjmedia_vid_dev_hwnd window;
416
417     /**
418      * Video display size. This setting is optional, and will only be used 
419      * if PJMEDIA_VID_DEV_CAP_OUTPUT_RESIZE is set in the flags.
420      */
421     pjmedia_rect_size disp_size;
422
423     /**
424      * Video window position. This setting is optional, and will only be used
425      * if PJMEDIA_VID_DEV_CAP_OUTPUT_POSITION is set in the flags.
426      */
427     pjmedia_coord window_pos;
428
429     /**
430      * Video window's visibility. This setting is optional, and will only be
431      * used if PJMEDIA_VID_DEV_CAP_OUTPUT_HIDE is set in the flags.
432      */
433     pj_bool_t window_hide;
434
435     /**
436      * Enable built-in preview. This setting is optional and is only used
437      * if PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW capability is supported and
438      * set in the flags.
439      */
440     pj_bool_t native_preview;
441
442     /**
443      * Video orientation. This setting is optional and is only used if
444      * PJMEDIA_VID_DEV_CAP_ORIENTATION capability is supported and is
445      * set in the flags.
446      */
447     pjmedia_orient orient;
448
449     /**
450      * Video window flags. This setting is optional, and will only be used
451      * if PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW_FLAGS is set in the flags.
452      */
453     unsigned window_flags;
454
455 } pjmedia_vid_dev_param;
456
457
458 /** Forward declaration for video device factory */
459 typedef struct pjmedia_vid_dev_factory pjmedia_vid_dev_factory;
460
461 /* typedef for factory creation function */
462 typedef pjmedia_vid_dev_factory*
463 (*pjmedia_vid_dev_factory_create_func_ptr)(pj_pool_factory*);
464
465 /**
466  * Initialize pjmedia_vid_dev_switch_param.
467  *
468  * @param p         Parameter to be initialized.
469  */
470 PJ_INLINE(void)
471 pjmedia_vid_dev_switch_param_default(pjmedia_vid_dev_switch_param *p)
472 {
473     pj_bzero(p, sizeof(*p));
474     p->target_id = PJMEDIA_VID_INVALID_DEV;
475 }
476
477 /**
478  * Get string info for the specified capability.
479  *
480  * @param cap       The capability ID.
481  * @param p_desc    Optional pointer which will be filled with longer
482  *                  description about the capability.
483  *
484  * @return          Capability name.
485  */
486 PJ_DECL(const char*) pjmedia_vid_dev_cap_name(pjmedia_vid_dev_cap cap,
487                                               const char **p_desc);
488
489
490 /**
491  * Set a capability field value in #pjmedia_vid_dev_param structure. This will
492  * also set the flags field for the specified capability in the structure.
493  *
494  * @param param     The structure.
495  * @param cap       The video capability which value is to be set.
496  * @param pval      Pointer to value. Please see the type of value to
497  *                  be supplied in the pjmedia_vid_dev_cap documentation.
498  *
499  * @return          PJ_SUCCESS on successful operation or the appropriate
500  *                  error code.
501  */
502 PJ_DECL(pj_status_t)
503 pjmedia_vid_dev_param_set_cap(pjmedia_vid_dev_param *param,
504                               pjmedia_vid_dev_cap cap,
505                               const void *pval);
506
507
508 /**
509  * Get a capability field value from #pjmedia_vid_dev_param structure. This
510  * function will return PJMEDIA_EVID_INVCAP error if the flag for that
511  * capability is not set in the flags field in the structure.
512  *
513  * @param param     The structure.
514  * @param cap       The video capability which value is to be retrieved.
515  * @param pval      Pointer to value. Please see the type of value to
516  *                  be supplied in the pjmedia_vid_dev_cap documentation.
517  *
518  * @return          PJ_SUCCESS on successful operation or the appropriate
519  *                  error code.
520  */
521 PJ_DECL(pj_status_t)
522 pjmedia_vid_dev_param_get_cap(const pjmedia_vid_dev_param *param,
523                               pjmedia_vid_dev_cap cap,
524                               void *pval);
525
526 /**
527  * Initialize the video device subsystem. This will register all supported
528  * video device factories to the video device subsystem. This function may be
529  * called more than once, but each call to this function must have the
530  * corresponding #pjmedia_vid_dev_subsys_shutdown() call.
531  *
532  * @param pf        The pool factory.
533  *
534  * @return          PJ_SUCCESS on successful operation or the appropriate
535  *                  error code.
536  */
537 PJ_DECL(pj_status_t) pjmedia_vid_dev_subsys_init(pj_pool_factory *pf);
538
539
540 /**
541  * Get the pool factory registered to the video device subsystem.
542  *
543  * @return          The pool factory.
544  */
545 PJ_DECL(pj_pool_factory*) pjmedia_vid_dev_subsys_get_pool_factory(void);
546
547
548 /**
549  * Shutdown the video device subsystem. This will destroy all video device
550  * factories registered in the video device subsystem. Note that currently
551  * opened video streams may or may not be closed, depending on the
552  * implementation of the video device factories.
553  *
554  * @return          PJ_SUCCESS on successful operation or the appropriate
555  *                  error code.
556  */
557 PJ_DECL(pj_status_t) pjmedia_vid_dev_subsys_shutdown(void);
558
559
560 /**
561  * Register a supported video device factory to the video device subsystem.
562  * Application can either register a function to create the factory, or
563  * an instance of an already created factory.
564  *
565  * This function can only be called after calling
566  * #pjmedia_vid_dev_subsys_init().
567  *
568  * @param vdf       The factory creation function. Either vdf or factory
569  *                  argument must be specified.
570  * @param factory   Factory instance. Either vdf or factory
571  *                  argument must be specified.
572  *
573  * @return          PJ_SUCCESS on successful operation or the appropriate
574  *                  error code.
575  */
576 PJ_DECL(pj_status_t)
577 pjmedia_vid_register_factory(pjmedia_vid_dev_factory_create_func_ptr vdf,
578                              pjmedia_vid_dev_factory *factory);
579
580
581 /**
582  * Unregister a video device factory from the video device subsystem. This
583  * function can only be called after calling #pjmedia_vid_dev_subsys_init().
584  * Devices from this factory will be unlisted. If a device from this factory
585  * is currently in use, then the behavior is undefined.
586  *
587  * @param vdf       The video device factory. Either vdf or factory argument
588  *                  must be specified.
589  * @param factory   The factory instance. Either vdf or factory argument
590  *                  must be specified.
591  *
592  * @return          PJ_SUCCESS on successful operation or the appropriate
593  *                  error code.
594  */
595 PJ_DECL(pj_status_t)
596 pjmedia_vid_unregister_factory(pjmedia_vid_dev_factory_create_func_ptr vdf,
597                                pjmedia_vid_dev_factory *factory);
598
599
600 /**
601  * Refresh the list of video devices installed in the system. This function
602  * will only refresh the list of videoo device so all active video streams will
603  * be unaffected. After refreshing the device list, application MUST make sure
604  * to update all index references to video devices (i.e. all variables of type
605  * pjmedia_vid_dev_index) before calling any function that accepts video device
606  * index as its parameter.
607  *
608  * @return              PJ_SUCCESS on successful operation or the appropriate
609  *                      error code.
610  */
611 PJ_DECL(pj_status_t) pjmedia_vid_dev_refresh(void);
612
613
614 /**
615  * Get the number of video devices installed in the system.
616  *
617  * @return          The number of video devices installed in the system.
618  */
619 PJ_DECL(unsigned) pjmedia_vid_dev_count(void);
620
621
622 /**
623  * Get device information.
624  *
625  * @param id        The video device ID.
626  * @param info      The device information which will be filled in by this
627  *                  function once it returns successfully.
628  *
629  * @return          PJ_SUCCESS on successful operation or the appropriate
630  *                  error code.
631  */
632 PJ_DECL(pj_status_t) pjmedia_vid_dev_get_info(pjmedia_vid_dev_index id,
633                                               pjmedia_vid_dev_info *info);
634
635
636 /**
637  * Lookup device index based on the driver and device name.
638  *
639  * @param drv_name  The driver name.
640  * @param dev_name  The device name.
641  * @param id        Pointer to store the returned device ID.
642  *
643  * @return          PJ_SUCCESS if the device can be found.
644  */
645 PJ_DECL(pj_status_t) pjmedia_vid_dev_lookup(const char *drv_name,
646                                             const char *dev_name,
647                                             pjmedia_vid_dev_index *id);
648
649
650 /**
651  * Initialize the video device parameters with default values for the
652  * specified device.
653  *
654  * @param id        The video device ID.
655  * @param param     The video device parameters which will be initialized
656  *                  by this function once it returns successfully.
657  *
658  * @return          PJ_SUCCESS on successful operation or the appropriate
659  *                  error code.
660  */
661 PJ_DECL(pj_status_t)
662 pjmedia_vid_dev_default_param(pj_pool_t *pool,
663                               pjmedia_vid_dev_index id,
664                               pjmedia_vid_dev_param *param);
665
666
667 /**
668  * Open video stream object using the specified parameters. If stream is
669  * created successfully, this function will return PJ_SUCCESS and the
670  * stream pointer will be returned in the p_strm argument.
671  *
672  * The opened stream may have been opened with different size and fps
673  * than the requested values in the \a param argument. Application should
674  * check the actual size and fps that the stream was opened with by inspecting
675  * the values in the \a param argument and see if they have changed. Also
676  * if the device ID in the \a param specifies default device, it may be
677  * replaced with the actual device ID upon return.
678  *
679  * @param param         Sound device parameters to be used for the stream.
680  * @param cb            Pointer to structure containing video stream
681  *                      callbacks.
682  * @param user_data     Arbitrary user data, which will be given back in the
683  *                      callbacks.
684  * @param p_strm        Pointer to receive the video stream.
685  *
686  * @return              PJ_SUCCESS on successful operation or the appropriate
687  *                      error code.
688  */
689 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_create(
690                                             pjmedia_vid_dev_param *param,
691                                             const pjmedia_vid_dev_cb *cb,
692                                             void *user_data,
693                                             pjmedia_vid_dev_stream **p_strm);
694
695 /**
696  * Get the running parameters for the specified video stream.
697  *
698  * @param strm      The video stream.
699  * @param param     Video stream parameters to be filled in by this
700  *                  function once it returns successfully.
701  *
702  * @return          PJ_SUCCESS on successful operation or the appropriate
703  *                  error code.
704  */
705 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_get_param(
706                                             pjmedia_vid_dev_stream *strm,
707                                             pjmedia_vid_dev_param *param);
708
709 /**
710  * Get the value of a specific capability of the video stream.
711  *
712  * @param strm      The video stream.
713  * @param cap       The video capability which value is to be retrieved.
714  * @param value     Pointer to value to be filled in by this function
715  *                  once it returns successfully.  Please see the type
716  *                  of value to be supplied in the pjmedia_vid_dev_cap
717  *                  documentation.
718  *
719  * @return          PJ_SUCCESS on successful operation or the appropriate
720  *                  error code.
721  */
722 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_get_cap(
723                                             pjmedia_vid_dev_stream *strm,
724                                             pjmedia_vid_dev_cap cap,
725                                             void *value);
726
727 /**
728  * Set the value of a specific capability of the video stream.
729  *
730  * @param strm      The video stream.
731  * @param cap       The video capability which value is to be set.
732  * @param value     Pointer to value. Please see the type of value to
733  *                  be supplied in the pjmedia_vid_dev_cap documentation.
734  *
735  * @return          PJ_SUCCESS on successful operation or the appropriate
736  *                  error code.
737  */
738 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_set_cap(
739                                             pjmedia_vid_dev_stream *strm,
740                                             pjmedia_vid_dev_cap cap,
741                                             const void *value);
742
743 /**
744  * Start the stream.
745  *
746  * @param strm      The video stream.
747  *
748  * @return          PJ_SUCCESS on successful operation or the appropriate
749  *                  error code.
750  */
751 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_start(
752                                             pjmedia_vid_dev_stream *strm);
753
754 /**
755  * Query whether the stream has been started.
756  *
757  * @param strm      The video stream
758  *
759  * @return          PJ_TRUE if the video stream has been started.
760  */
761 PJ_DECL(pj_bool_t) pjmedia_vid_dev_stream_is_running(pjmedia_vid_dev_stream *strm);
762
763
764 /**
765  * Request one frame from the stream. Application needs to call this function
766  * periodically only if the stream doesn't support "active interface", i.e.
767  * the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.
768  *
769  * @param strm      The video stream.
770  * @param frame     The video frame to be filled by the device.
771  *
772  * @return          PJ_SUCCESS on successful operation or the appropriate
773  *                  error code.
774  */
775 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_get_frame(
776                                             pjmedia_vid_dev_stream *strm,
777                                             pjmedia_frame *frame);
778
779 /**
780  * Put one frame to the stream. Application needs to call this function
781  * periodically only if the stream doesn't support "active interface", i.e.
782  * the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.
783  *
784  * @param strm      The video stream.
785  * @param frame     The video frame to put to the device.
786  *
787  * @return          PJ_SUCCESS on successful operation or the appropriate
788  *                  error code.
789  */
790 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_put_frame(
791                                             pjmedia_vid_dev_stream *strm,
792                                             const pjmedia_frame *frame);
793
794 /**
795  * Stop the stream.
796  *
797  * @param strm      The video stream.
798  *
799  * @return          PJ_SUCCESS on successful operation or the appropriate
800  *                  error code.
801  */
802 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_stop(
803                                             pjmedia_vid_dev_stream *strm);
804
805 /**
806  * Destroy the stream.
807  *
808  * @param strm      The video stream.
809  *
810  * @return          PJ_SUCCESS on successful operation or the appropriate
811  *                  error code.
812  */
813 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_destroy(
814                                             pjmedia_vid_dev_stream *strm);
815
816
817 /**
818  * @}
819  */
820
821 PJ_END_DECL
822
823
824 #endif    /* __PJMEDIA_VIDEODEV_VIDEODEV_H__ */