API Reference. More...

Data Structures
struct	pjmedia_vid_dev_hwnd

struct	pjmedia_vid_dev_switch_param

struct	pjmedia_vid_dev_info

struct	pjmedia_vid_dev_cb

struct	pjmedia_vid_dev_param

struct	pjmedia_vid_driver

struct	pjmedia_vid_subsys

Typedefs
typedef pj_int32_t	pjmedia_vid_dev_index

typedef pjmedia_vid_dev_factory (	pjmedia_vid_dev_factory_create_func_ptr) (pj_pool_factory *)

Enumerations
enum	pjmedia_vid_dev_hwnd_type { PJMEDIA_VID_DEV_HWND_TYPE_NONE , PJMEDIA_VID_DEV_HWND_TYPE_WINDOWS , PJMEDIA_VID_DEV_HWND_TYPE_IOS , PJMEDIA_VID_DEV_HWND_TYPE_ANDROID }

enum	pjmedia_vid_dev_wnd_flag { PJMEDIA_VID_DEV_WND_BORDER = 1 , PJMEDIA_VID_DEV_WND_RESIZABLE = 2 }

enum	pjmedia_vid_dev_std_index { PJMEDIA_VID_DEFAULT_CAPTURE_DEV = -1 , PJMEDIA_VID_DEFAULT_RENDER_DEV = -2 , PJMEDIA_VID_INVALID_DEV = -3 }

enum	pjmedia_vid_dev_fullscreen_flag { PJMEDIA_VID_DEV_WINDOWED = 0 , PJMEDIA_VID_DEV_FULLSCREEN = 1 , PJMEDIA_VID_DEV_FULLSCREEN_DESKTOP = 2 }

enum	pjmedia_vid_dev_cap { PJMEDIA_VID_DEV_CAP_FORMAT = 1 , PJMEDIA_VID_DEV_CAP_INPUT_SCALE = 2 , PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW = 4 , PJMEDIA_VID_DEV_CAP_OUTPUT_RESIZE = 8 , PJMEDIA_VID_DEV_CAP_OUTPUT_POSITION = 16 , PJMEDIA_VID_DEV_CAP_OUTPUT_HIDE = 32 , PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW = 64 , PJMEDIA_VID_DEV_CAP_ORIENTATION = 128 , PJMEDIA_VID_DEV_CAP_SWITCH = 256 , PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW_FLAGS = 512 , PJMEDIA_VID_DEV_CAP_OUTPUT_FULLSCREEN = 1024 , PJMEDIA_VID_DEV_CAP_MAX = 16384 }

Functions
pj_status_t	pjmedia_vid_dev_subsys_init (pj_pool_factory *pf)

pj_pool_factory *	pjmedia_vid_dev_subsys_get_pool_factory (void)

pj_status_t	pjmedia_vid_dev_subsys_shutdown (void)

pj_status_t	pjmedia_vid_register_factory (pjmedia_vid_dev_factory_create_func_ptr vdf, pjmedia_vid_dev_factory *factory)

pj_status_t	pjmedia_vid_unregister_factory (pjmedia_vid_dev_factory_create_func_ptr vdf, pjmedia_vid_dev_factory *factory)

pjmedia_vid_subsys *	pjmedia_get_vid_subsys (void)

pj_status_t	pjmedia_vid_driver_init (unsigned drv_idx, pj_bool_t refresh)

void	pjmedia_vid_driver_deinit (unsigned drv_idx)

void	pjmedia_vid_dev_switch_param_default (pjmedia_vid_dev_switch_param *p)

const char *	pjmedia_vid_dev_cap_name (pjmedia_vid_dev_cap cap, const char **p_desc)

pj_status_t	pjmedia_vid_dev_param_set_cap (pjmedia_vid_dev_param param, pjmedia_vid_dev_cap cap, const void pval)

pj_status_t	pjmedia_vid_dev_param_get_cap (const pjmedia_vid_dev_param param, pjmedia_vid_dev_cap cap, void pval)

pj_status_t	pjmedia_vid_dev_refresh (void)

unsigned	pjmedia_vid_dev_count (void)

pj_status_t	pjmedia_vid_dev_get_info (pjmedia_vid_dev_index id, pjmedia_vid_dev_info *info)

pj_status_t	pjmedia_vid_dev_lookup (const char drv_name, const char dev_name, pjmedia_vid_dev_index *id)

pj_status_t	pjmedia_vid_dev_default_param (pj_pool_t pool, pjmedia_vid_dev_index id, pjmedia_vid_dev_param param)

pj_status_t	pjmedia_vid_dev_stream_create (pjmedia_vid_dev_param param, const pjmedia_vid_dev_cb cb, void user_data, pjmedia_vid_dev_stream *p_strm)

pj_status_t	pjmedia_vid_dev_stream_get_param (pjmedia_vid_dev_stream strm, pjmedia_vid_dev_param param)

pj_status_t	pjmedia_vid_dev_stream_get_cap (pjmedia_vid_dev_stream strm, pjmedia_vid_dev_cap cap, void value)

pj_status_t	pjmedia_vid_dev_stream_set_cap (pjmedia_vid_dev_stream strm, pjmedia_vid_dev_cap cap, const void value)

pj_status_t	pjmedia_vid_dev_stream_start (pjmedia_vid_dev_stream *strm)

pj_bool_t	pjmedia_vid_dev_stream_is_running (pjmedia_vid_dev_stream *strm)

pj_status_t	pjmedia_vid_dev_stream_get_frame (pjmedia_vid_dev_stream strm, pjmedia_frame frame)

pj_status_t	pjmedia_vid_dev_stream_put_frame (pjmedia_vid_dev_stream strm, const pjmedia_frame frame)

pj_status_t	pjmedia_vid_dev_stream_stop (pjmedia_vid_dev_stream *strm)

pj_status_t	pjmedia_vid_dev_stream_destroy (pjmedia_vid_dev_stream *strm)

Detailed Description

Typedef Documentation

◆ pjmedia_vid_dev_index

typedef pj_int32_t pjmedia_vid_dev_index

Type for device index.

Enumeration Type Documentation

◆ pjmedia_vid_dev_hwnd_type

enum pjmedia_vid_dev_hwnd_type

Enumeration of window handle type.

Enumerator
PJMEDIA_VID_DEV_HWND_TYPE_NONE	Type none.
PJMEDIA_VID_DEV_HWND_TYPE_WINDOWS	Native window handle on Windows.
PJMEDIA_VID_DEV_HWND_TYPE_IOS	Native view on iOS.
PJMEDIA_VID_DEV_HWND_TYPE_ANDROID	Native window handle on Android.

◆ pjmedia_vid_dev_wnd_flag

enum pjmedia_vid_dev_wnd_flag

Enumeration of window flags.

Enumerator
PJMEDIA_VID_DEV_WND_BORDER	Window with border.
PJMEDIA_VID_DEV_WND_RESIZABLE	Window can be resized.

◆ pjmedia_vid_dev_std_index

enum pjmedia_vid_dev_std_index

Device index constants.

Enumerator
PJMEDIA_VID_DEFAULT_CAPTURE_DEV	Constant to denote default capture device
PJMEDIA_VID_DEFAULT_RENDER_DEV	Constant to denote default render device
PJMEDIA_VID_INVALID_DEV	Constant to denote invalid device index.

◆ pjmedia_vid_dev_fullscreen_flag

enum pjmedia_vid_dev_fullscreen_flag

Enumeration of window fullscreen flags.

Enumerator
PJMEDIA_VID_DEV_WINDOWED	Windowed or disable fullscreen.
PJMEDIA_VID_DEV_FULLSCREEN	Fullscreen enabled, video mode may be changed.
PJMEDIA_VID_DEV_FULLSCREEN_DESKTOP	Fullscreen enabled by resizing video frame to match to the desktop, video mode will not be changed.

◆ pjmedia_vid_dev_cap

enum pjmedia_vid_dev_cap

This enumeration identifies various video device capabilities. These video capabilities indicates what features are supported by the underlying video device implementation.

Applications get these capabilities in the pjmedia_vid_dev_info structure.

Application can also set the specific features/capabilities when opening the video stream by setting the flags member of pjmedia_vid_dev_param structure.

Once video stream is running, application can also retrieve or set some specific video capability, by using pjmedia_vid_dev_stream_get_cap() and pjmedia_vid_dev_stream_set_cap() and specifying the desired capability. The value of the capability is specified as pointer, and application needs to supply the pointer with the correct value, according to the documentation of each of the capability.

Enumerator
PJMEDIA_VID_DEV_CAP_FORMAT	Support for video formats. The value of this capability is represented by pjmedia_format structure.
PJMEDIA_VID_DEV_CAP_INPUT_SCALE	Support for video input scaling
PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW	Support for returning the native window handle of the video window. For renderer, this means the window handle of the renderer window, while for capture, this means the window handle of the native preview, only if the device supports PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW capability. The value of this capability is pointer to pjmedia_vid_dev_hwnd structure.
PJMEDIA_VID_DEV_CAP_OUTPUT_RESIZE	Support for resizing video output. This capability SHOULD be implemented by renderer, to alter the video output dimension on the fly. Value is pjmedia_rect_size.
PJMEDIA_VID_DEV_CAP_OUTPUT_POSITION	Support for setting the video window's position. Value is pjmedia_coord specifying the window's new coordinate.
PJMEDIA_VID_DEV_CAP_OUTPUT_HIDE	Support for setting the video output's visibility. The value of this capability is a pj_bool_t containing boolean PJ_TRUE or PJ_FALSE.
PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW	Support for native preview capability in capture devices. Value is pj_bool_t. With native preview, capture device can be instructed to show or hide a preview window showing video directly from the camera by setting this capability to PJ_TRUE or PJ_FALSE. Once the preview is started, application may use PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW capability to query the video window. The value of this capability is a pj_bool_t containing boolean PJ_TRUE or PJ_FALSE.
PJMEDIA_VID_DEV_CAP_ORIENTATION	Support for changing video orientation. For a renderer device, changing video orientation in will potentially affect the size of render window, i.e: width and height swap. For a capture device, the video will be rotated but the size of the video frame will stay the same, so the video may be resized or stretched. The value of this capability is pjmedia_orient.
PJMEDIA_VID_DEV_CAP_SWITCH	Support for fast switching to another device. A video stream with this capability allows replacing of its underlying device with another device, saving the user from opening a new video stream and gets a much faster and smoother switching action. Note that even when this capability is supported by a device, it may not be able to switch to arbitrary device. Application must always check the return value of the operation to verify that switching has occurred. This capability is currently write-only (i.e. set-only). The value of this capability is pointer to pjmedia_vid_dev_switch_param structure.
PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW_FLAGS	Support for setting the output video window's flags. The value of this capability is a bitmask combination of pjmedia_vid_dev_wnd_flag.
PJMEDIA_VID_DEV_CAP_OUTPUT_FULLSCREEN	Support for setting the output video window full screen.
PJMEDIA_VID_DEV_CAP_MAX	End of standard capability

Function Documentation

◆ pjmedia_vid_dev_subsys_init()

pj_status_t pjmedia_vid_dev_subsys_init ( pj_pool_factory * pf )

Initialize the video device subsystem. This will register all supported video device factories to the video device subsystem. This function may be called more than once, but each call to this function must have the corresponding pjmedia_vid_dev_subsys_shutdown() call.

Parameters

pf	The pool factory.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_subsys_get_pool_factory()

pj_pool_factory * pjmedia_vid_dev_subsys_get_pool_factory ( void )

Get the pool factory registered to the video device subsystem.

Returns: The pool factory.

◆ pjmedia_vid_dev_subsys_shutdown()

pj_status_t pjmedia_vid_dev_subsys_shutdown ( void )

Shutdown the video device subsystem. This will destroy all video device factories registered in the video device subsystem. Note that currently opened video streams may or may not be closed, depending on the implementation of the video device factories.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_register_factory()

pj_status_t pjmedia_vid_register_factory	(	pjmedia_vid_dev_factory_create_func_ptr	vdf,
		pjmedia_vid_dev_factory *	factory
	)

Register a supported video device factory to the video device subsystem. Application can either register a function to create the factory, or an instance of an already created factory.

This function can only be called after calling pjmedia_vid_dev_subsys_init().

Parameters

vdf	The factory creation function. Either vdf or factory argument must be specified.
factory	Factory instance. Either vdf or factory argument must be specified.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_unregister_factory()

pj_status_t pjmedia_vid_unregister_factory	(	pjmedia_vid_dev_factory_create_func_ptr	vdf,
		pjmedia_vid_dev_factory *	factory
	)

Unregister a video device factory from the video device subsystem. This function can only be called after calling pjmedia_vid_dev_subsys_init(). Devices from this factory will be unlisted. If a device from this factory is currently in use, then the behavior is undefined.

Parameters

vdf	The video device factory. Either vdf or factory argument must be specified.
factory	The factory instance. Either vdf or factory argument must be specified.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_get_vid_subsys()

pjmedia_vid_subsys * pjmedia_get_vid_subsys ( void )

Get the video subsystem.

Returns: The video subsystem.

◆ pjmedia_vid_driver_init()

pj_status_t pjmedia_vid_driver_init	(	unsigned	drv_idx,
		pj_bool_t	refresh
	)

Initialize the video driver.

Parameters

drv_idx	The index of the video driver.
refresh	Specify non-zero to refresh the video driver.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_driver_deinit()

void pjmedia_vid_driver_deinit ( unsigned drv_idx )

Deinitialize the video driver.

Parameters

drv_idx The index of the video driver.

References PJ_INLINE.

◆ pjmedia_vid_dev_switch_param_default()

void pjmedia_vid_dev_switch_param_default ( pjmedia_vid_dev_switch_param * p )

Initialize pjmedia_vid_dev_switch_param.

Parameters

p	Parameter to be initialized.

References pj_bzero(), and PJMEDIA_VID_INVALID_DEV.

◆ pjmedia_vid_dev_cap_name()

const char * pjmedia_vid_dev_cap_name	(	pjmedia_vid_dev_cap	cap,
		const char **	p_desc
	)

Get string info for the specified capability.

Parameters

cap	The capability ID.
p_desc	Optional pointer which will be filled with longer description about the capability.

Returns: Capability name.

◆ pjmedia_vid_dev_param_set_cap()

pj_status_t pjmedia_vid_dev_param_set_cap	(	pjmedia_vid_dev_param *	param,
		pjmedia_vid_dev_cap	cap,
		const void *	pval
	)

Set a capability field value in pjmedia_vid_dev_param structure. This will also set the flags field for the specified capability in the structure.

Parameters

param	The structure.
cap	The video capability which value is to be set.
pval	Pointer to value. Please see the type of value to be supplied in the pjmedia_vid_dev_cap documentation.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_param_get_cap()

pj_status_t pjmedia_vid_dev_param_get_cap	(	const pjmedia_vid_dev_param *	param,
		pjmedia_vid_dev_cap	cap,
		void *	pval
	)

Get a capability field value from pjmedia_vid_dev_param structure. This function will return PJMEDIA_EVID_INVCAP error if the flag for that capability is not set in the flags field in the structure.

Parameters

param	The structure.
cap	The video capability which value is to be retrieved.
pval	Pointer to value. Please see the type of value to be supplied in the pjmedia_vid_dev_cap documentation.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_refresh()

pj_status_t pjmedia_vid_dev_refresh ( void )

Refresh the list of video devices installed in the system. This function will only refresh the list of videoo device so all active video streams will be unaffected. After refreshing the device list, application MUST make sure to update all index references to video devices (i.e. all variables of type pjmedia_vid_dev_index) before calling any function that accepts video device index as its parameter.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_count()

unsigned pjmedia_vid_dev_count ( void )

Get the number of video devices installed in the system.

Returns: The number of video devices installed in the system.

◆ pjmedia_vid_dev_get_info()

pj_status_t pjmedia_vid_dev_get_info	(	pjmedia_vid_dev_index	id,
		pjmedia_vid_dev_info *	info
	)

Get device information.

Parameters

id	The video device ID.
info	The device information which will be filled in by this function once it returns successfully.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_lookup()

pj_status_t pjmedia_vid_dev_lookup	(	const char *	drv_name,
		const char *	dev_name,
		pjmedia_vid_dev_index *	id
	)

Lookup device index based on the driver and device name.

Parameters

drv_name	The driver name.
dev_name	The device name.
id	Pointer to store the returned device ID.

Returns: PJ_SUCCESS if the device can be found.

◆ pjmedia_vid_dev_default_param()

pj_status_t pjmedia_vid_dev_default_param	(	pj_pool_t *	pool,
		pjmedia_vid_dev_index	id,
		pjmedia_vid_dev_param *	param
	)

Initialize the video device parameters with default values for the specified device.

Parameters

pool	The pool.
id	The video device ID.
param	The video device parameters which will be initialized by this function once it returns successfully.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_stream_create()

pj_status_t pjmedia_vid_dev_stream_create	(	pjmedia_vid_dev_param *	param,
		const pjmedia_vid_dev_cb *	cb,
		void *	user_data,
		pjmedia_vid_dev_stream **	p_strm
	)

Open video stream object using the specified parameters. If stream is created successfully, this function will return PJ_SUCCESS and the stream pointer will be returned in the p_strm argument.

The opened stream may have been opened with different size and fps than the requested values in the param argument. Application should check the actual size and fps that the stream was opened with by inspecting the values in the param argument and see if they have changed. Also if the device ID in the param specifies default device, it may be replaced with the actual device ID upon return.

Parameters

param	On input, it specifies the video device parameters to be used for the stream. On output, this will be set to the actual video device parameters used to open the stream.
cb	Pointer to structure containing video stream callbacks.
user_data	Arbitrary user data, which will be given back in the callbacks.
p_strm	Pointer to receive the video stream.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_stream_get_param()

pj_status_t pjmedia_vid_dev_stream_get_param	(	pjmedia_vid_dev_stream *	strm,
		pjmedia_vid_dev_param *	param
	)

Get the running parameters for the specified video stream.

Parameters

strm	The video stream.
param	Video stream parameters to be filled in by this function once it returns successfully.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_stream_get_cap()

pj_status_t pjmedia_vid_dev_stream_get_cap	(	pjmedia_vid_dev_stream *	strm,
		pjmedia_vid_dev_cap	cap,
		void *	value
	)

Get the value of a specific capability of the video stream.

Parameters

strm	The video stream.
cap	The video capability which value is to be retrieved.
value	Pointer to value to be filled in by this function once it returns successfully. Please see the type of value to be supplied in the pjmedia_vid_dev_cap documentation.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_stream_set_cap()

pj_status_t pjmedia_vid_dev_stream_set_cap	(	pjmedia_vid_dev_stream *	strm,
		pjmedia_vid_dev_cap	cap,
		const void *	value
	)

Set the value of a specific capability of the video stream.

Parameters

strm	The video stream.
cap	The video capability which value is to be set.
value	Pointer to value. Please see the type of value to be supplied in the pjmedia_vid_dev_cap documentation.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_stream_start()

pj_status_t pjmedia_vid_dev_stream_start ( pjmedia_vid_dev_stream * strm )

Start the stream.

Parameters

strm	The video stream.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_stream_is_running()

pj_bool_t pjmedia_vid_dev_stream_is_running ( pjmedia_vid_dev_stream * strm )

Query whether the stream has been started.

Parameters

strm	The video stream

Returns: PJ_TRUE if the video stream has been started.

◆ pjmedia_vid_dev_stream_get_frame()

pj_status_t pjmedia_vid_dev_stream_get_frame	(	pjmedia_vid_dev_stream *	strm,
		pjmedia_frame *	frame
	)

Request one frame from the stream. Application needs to call this function periodically only if the stream doesn't support "active interface", i.e. the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.

Parameters

strm	The video stream.
frame	The video frame to be filled by the device.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_stream_put_frame()

pj_status_t pjmedia_vid_dev_stream_put_frame	(	pjmedia_vid_dev_stream *	strm,
		const pjmedia_frame *	frame
	)

Put one frame to the stream. Application needs to call this function periodically only if the stream doesn't support "active interface", i.e. the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.

Parameters

strm	The video stream.
frame	The video frame to put to the device.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_stream_stop()

pj_status_t pjmedia_vid_dev_stream_stop ( pjmedia_vid_dev_stream * strm )

Stop the stream.

Parameters

strm	The video stream.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

◆ pjmedia_vid_dev_stream_destroy()

pj_status_t pjmedia_vid_dev_stream_destroy ( pjmedia_vid_dev_stream * strm )

Destroy the stream.

Parameters

strm	The video stream.

Returns: PJ_SUCCESS on successful operation or the appropriate error code.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ pjmedia_vid_dev_index

Enumeration Type Documentation

◆ pjmedia_vid_dev_hwnd_type

◆ pjmedia_vid_dev_wnd_flag

◆ pjmedia_vid_dev_std_index

◆ pjmedia_vid_dev_fullscreen_flag

◆ pjmedia_vid_dev_cap

Function Documentation

◆ pjmedia_vid_dev_subsys_init()

◆ pjmedia_vid_dev_subsys_get_pool_factory()

◆ pjmedia_vid_dev_subsys_shutdown()

◆ pjmedia_vid_register_factory()

◆ pjmedia_vid_unregister_factory()

◆ pjmedia_get_vid_subsys()

◆ pjmedia_vid_driver_init()

◆ pjmedia_vid_driver_deinit()

◆ pjmedia_vid_dev_switch_param_default()

◆ pjmedia_vid_dev_cap_name()

◆ pjmedia_vid_dev_param_set_cap()

◆ pjmedia_vid_dev_param_get_cap()

◆ pjmedia_vid_dev_refresh()

◆ pjmedia_vid_dev_count()

◆ pjmedia_vid_dev_get_info()

◆ pjmedia_vid_dev_lookup()

◆ pjmedia_vid_dev_default_param()

◆ pjmedia_vid_dev_stream_create()

◆ pjmedia_vid_dev_stream_get_param()

◆ pjmedia_vid_dev_stream_get_cap()

◆ pjmedia_vid_dev_stream_set_cap()

◆ pjmedia_vid_dev_stream_start()

◆ pjmedia_vid_dev_stream_is_running()

◆ pjmedia_vid_dev_stream_get_frame()

◆ pjmedia_vid_dev_stream_put_frame()

◆ pjmedia_vid_dev_stream_stop()

◆ pjmedia_vid_dev_stream_destroy()