← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.2.1/pjmedia/include/pjmedia-videodev/videodev.h

  • Committer: Package Import Robot
  • Author(s): Francois Marier, Francois Marier, Mark Purcell
  • Date: 2014-10-18 15:08:50 UTC
  • mfrom: (1.1.12)
  • mto: This revision was merged to the branch mainline in revision 29.
  • Revision ID: package-import@ubuntu.com-20141018150850-2exfk34ckb15pcwi
Tags: 1.4.1-0.1
http://bugs.debian.org/759576
http://bugs.debian.org/741130
[ Francois Marier ]
* Non-maintainer upload
* New upstream release (closes: #759576, #741130)
  - debian/rules +PJPROJECT_VERSION := 2.2.1
  - add upstream patch to fix broken TLS support
  - add patch to fix pjproject regression

[ Mark Purcell ]
* Build-Depends:
  - sflphone-daemon + libavformat-dev, libavcodec-dev, libswscale-dev,
  libavdevice-dev, libavutil-dev
  - sflphone-gnome + libclutter-gtk-1.0-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.2.1/pjmedia/include/pjmedia-videodev/videodev.h
 
1
/* $Id: videodev.h 4704 2014-01-16 05:30:46Z ming $ */
 
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 pjmedia_vid_dev_std_index
 
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         On input, it specifies the video device parameters
 
680
 *                      to be used for the stream. On output, this will be
 
681
 *                      set to the actual video device parameters used to
 
682
 *                      open the stream.
 
683
 * @param cb            Pointer to structure containing video stream
 
684
 *                      callbacks.
 
685
 * @param user_data     Arbitrary user data, which will be given back in the
 
686
 *                      callbacks.
 
687
 * @param p_strm        Pointer to receive the video stream.
 
688
 *
 
689
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
690
 *                      error code.
 
691
 */
 
692
PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_create(
 
693
                                            pjmedia_vid_dev_param *param,
 
694
                                            const pjmedia_vid_dev_cb *cb,
 
695
                                            void *user_data,
 
696
                                            pjmedia_vid_dev_stream **p_strm);
 
697
 
 
698
/**
 
699
 * Get the running parameters for the specified video stream.
 
700
 *
 
701
 * @param strm      The video stream.
 
702
 * @param param     Video stream parameters to be filled in by this
 
703
 *                  function once it returns successfully.
 
704
 *
 
705
 * @return          PJ_SUCCESS on successful operation or the appropriate
 
706
 *                  error code.
 
707
 */
 
708
PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_get_param(
 
709
                                            pjmedia_vid_dev_stream *strm,
 
710
                                            pjmedia_vid_dev_param *param);
 
711
 
 
712
/**
 
713
 * Get the value of a specific capability of the video stream.
 
714
 *
 
715
 * @param strm      The video stream.
 
716
 * @param cap       The video capability which value is to be retrieved.
 
717
 * @param value     Pointer to value to be filled in by this function
 
718
 *                  once it returns successfully.  Please see the type
 
719
 *                  of value to be supplied in the pjmedia_vid_dev_cap
 
720
 *                  documentation.
 
721
 *
 
722
 * @return          PJ_SUCCESS on successful operation or the appropriate
 
723
 *                  error code.
 
724
 */
 
725
PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_get_cap(
 
726
                                            pjmedia_vid_dev_stream *strm,
 
727
                                            pjmedia_vid_dev_cap cap,
 
728
                                            void *value);
 
729
 
 
730
/**
 
731
 * Set the value of a specific capability of the video stream.
 
732
 *
 
733
 * @param strm      The video stream.
 
734
 * @param cap       The video capability which value is to be set.
 
735
 * @param value     Pointer to value. Please see the type of value to
 
736
 *                  be supplied in the pjmedia_vid_dev_cap documentation.
 
737
 *
 
738
 * @return          PJ_SUCCESS on successful operation or the appropriate
 
739
 *                  error code.
 
740
 */
 
741
PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_set_cap(
 
742
                                            pjmedia_vid_dev_stream *strm,
 
743
                                            pjmedia_vid_dev_cap cap,
 
744
                                            const void *value);
 
745
 
 
746
/**
 
747
 * Start the stream.
 
748
 *
 
749
 * @param strm      The video stream.
 
750
 *
 
751
 * @return          PJ_SUCCESS on successful operation or the appropriate
 
752
 *                  error code.
 
753
 */
 
754
PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_start(
 
755
                                            pjmedia_vid_dev_stream *strm);
 
756
 
 
757
/**
 
758
 * Query whether the stream has been started.
 
759
 *
 
760
 * @param strm      The video stream
 
761
 *
 
762
 * @return          PJ_TRUE if the video stream has been started.
 
763
 */
 
764
PJ_DECL(pj_bool_t) pjmedia_vid_dev_stream_is_running(pjmedia_vid_dev_stream *strm);
 
765
 
 
766
 
 
767
/**
 
768
 * Request one frame from the stream. Application needs to call this function
 
769
 * periodically only if the stream doesn't support "active interface", i.e.
 
770
 * the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.
 
771
 *
 
772
 * @param strm      The video stream.
 
773
 * @param frame     The video frame to be filled by the device.
 
774
 *
 
775
 * @return          PJ_SUCCESS on successful operation or the appropriate
 
776
 *                  error code.
 
777
 */
 
778
PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_get_frame(
 
779
                                            pjmedia_vid_dev_stream *strm,
 
780
                                            pjmedia_frame *frame);
 
781
 
 
782
/**
 
783
 * Put one frame to the stream. Application needs to call this function
 
784
 * periodically only if the stream doesn't support "active interface", i.e.
 
785
 * the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.
 
786
 *
 
787
 * @param strm      The video stream.
 
788
 * @param frame     The video frame to put to the device.
 
789
 *
 
790
 * @return          PJ_SUCCESS on successful operation or the appropriate
 
791
 *                  error code.
 
792
 */
 
793
PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_put_frame(
 
794
                                            pjmedia_vid_dev_stream *strm,
 
795
                                            const pjmedia_frame *frame);
 
796
 
 
797
/**
 
798
 * Stop the stream.
 
799
 *
 
800
 * @param strm      The video stream.
 
801
 *
 
802
 * @return          PJ_SUCCESS on successful operation or the appropriate
 
803
 *                  error code.
 
804
 */
 
805
PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_stop(
 
806
                                            pjmedia_vid_dev_stream *strm);
 
807
 
 
808
/**
 
809
 * Destroy the stream.
 
810
 *
 
811
 * @param strm      The video stream.
 
812
 *
 
813
 * @return          PJ_SUCCESS on successful operation or the appropriate
 
814
 *                  error code.
 
815
 */
 
816
PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_destroy(
 
817
                                            pjmedia_vid_dev_stream *strm);
 
818
 
 
819
 
 
820
/**
 
821
 * @}
 
822
 */
 
823
 
 
824
PJ_END_DECL
 
825
 
 
826
 
 
827
#endif    /* __PJMEDIA_VIDEODEV_VIDEODEV_H__ */