Video Writer

Video writers allow compressing and saving images into video files. More...

Data Structures

struct

Represents a video writer. More...

Enumerations

enum	IC4_VIDEO_WRITER_TYPE { IC4_VIDEO_WRITER_MP4_H264 , IC4_VIDEO_WRITER_MP4_H265 } Defines the available video writer types. More...

Functions

bool	ic4_videowriter_create (enum IC4_VIDEO_WRITER_TYPE type, struct IC4_VIDEO_WRITER **ppVideoWriter) Creates a new video writer of the specified type.
struct IC4_VIDEO_WRITER *	ic4_videowriter_ref (struct IC4_VIDEO_WRITER *pVideoWriter) Increases the video writer's internal reference count by one.
void	ic4_videowriter_unref (struct IC4_VIDEO_WRITER *pVideoWriter) Decreases the video writer's internal reference count by one.
bool	ic4_videowriter_begin_file (struct IC4_VIDEO_WRITER pVideoWriter, const char file_name, const struct IC4_IMAGE_TYPE *image_type, double frame_rate) Opens a new video file ready to write images into.
bool	ic4_videowriter_finish_file (struct IC4_VIDEO_WRITER *pVideoWriter) Finishes writing a video file.
bool	ic4_videowriter_add_frame (struct IC4_VIDEO_WRITER pVideoWriter, struct IC4_IMAGE_BUFFER buffer) Adds an image to the currently open video file.
bool	ic4_videowriter_add_frame_copy (struct IC4_VIDEO_WRITER pVideoWriter, const struct IC4_IMAGE_BUFFER buffer) Adds an image to the currently open video file, copying its contents in the process.
bool	ic4_videowriter_get_property_map (struct IC4_VIDEO_WRITER pVideoWriter, struct IC4_PROPERTY_MAP *ppPropertyMap) Returns the property map for encoder configuration.

Detailed Description

Video writers allow compressing and saving images into video files.

There are multiple video writers available:

MP4 file with H264 encoder
MP4 file with H265 encoder

To create a new video writer, call ic4_videowriter_create() passing the desired video writer type.

After calling ic4_videowriter_begin_file(), repeatedly call ic4_videowriter_add_frame() to write images into the file. Call ic4_videowriter_finish_file() to finalize and close the file.

A video writer can be configured through the property map returned by ic4_videowriter_get_property_map(). For details on how to use such a property map, see Properties.

Enumeration Type Documentation

◆ IC4_VIDEO_WRITER_TYPE

enum IC4_VIDEO_WRITER_TYPE

Defines the available video writer types.

Enumerator
IC4_VIDEO_WRITER_MP4_H264	Create MP4 files with H.264 encoding.
IC4_VIDEO_WRITER_MP4_H265	Create MP4 files with H.265/HEVC encoding.

Function Documentation

◆ ic4_videowriter_add_frame()

bool ic4_videowriter_add_frame	(	struct IC4_VIDEO_WRITER *	pVideoWriter,
		struct IC4_IMAGE_BUFFER *	buffer
	)

Adds an image to the currently open video file.

Parameters

[in]	pVideoWriter	A video writer that previously began writing a file
[in]	buffer	An image buffer

Note: The image buffer's image type must be equal to the image_type parameter passed to ic4_videowriter_begin_file() when starting the file.
The video writer can retain a reference to the image buffer. This can delay the release and possible reuse of the image buffer. In this case, the buffer becomes shared, and is no longer safely writable (see ic4_imagebuffer_is_writable).
Use ic4_videowriter_add_frame_copy to always let the video writer immediately copy the data out of the image buffer.

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_videowriter_add_frame_copy()

bool ic4_videowriter_add_frame_copy	(	struct IC4_VIDEO_WRITER *	pVideoWriter,
		const struct IC4_IMAGE_BUFFER *	buffer
	)

Adds an image to the currently open video file, copying its contents in the process.

Parameters

[in]	pVideoWriter	A video writer that previously began writing a file
[in]	buffer	An image buffer

Note: The image buffer's image type must be equal to the image_type parameter passed to ic4_videowriter_begin_file() when starting the file.
The image buffer's contents will be copied, so that the buffer's reference count is not increased and it can be reused immedietely if the final reference is released.
Use ic4_videowriter_add_frame to avoid the copy operation if it is not necessary.

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_videowriter_begin_file()

bool ic4_videowriter_begin_file	(	struct IC4_VIDEO_WRITER *	pVideoWriter,
		const char *	file_name,
		const struct IC4_IMAGE_TYPE *	image_type,
		double	frame_rate
	)

Opens a new video file ready to write images into.

Parameters

[in]	pVideoWriter	A video writer
[in]	file_name	Name of the new video file
[in]	image_type	Image type of the images that are going to be written
[in]	frame_rate	Playback frame rate of the video file

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_videowriter_create()

bool ic4_videowriter_create	(	enum IC4_VIDEO_WRITER_TYPE	type,
		struct IC4_VIDEO_WRITER **	ppVideoWriter
	)

Creates a new video writer of the specified type.

Parameters

[in]	type	Selects the type of video writer to create
[out]	ppVideoWriter	Pointer to receive the handle of the new video writer When the video writer is no longer required, release the object reference using ic4_videowriter_unref().

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_videowriter_finish_file()

bool ic4_videowriter_finish_file ( struct IC4_VIDEO_WRITER * pVideoWriter )

Finishes writing a video file.

Parameters

[in] pVideoWriter A video writer that previously began writing a file

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_videowriter_get_property_map()

bool ic4_videowriter_get_property_map	(	struct IC4_VIDEO_WRITER *	pVideoWriter,
		struct IC4_PROPERTY_MAP **	ppPropertyMap
	)

Returns the property map for encoder configuration.

Parameters

[in]	pVideoWriter	A video writer
[out]	ppPropertyMap	Pointer to a handle that receives the property map. When the property map is longer required, call ic4_propmap_unref().

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_videowriter_ref()

struct IC4_VIDEO_WRITER * ic4_videowriter_ref ( struct IC4_VIDEO_WRITER * pVideoWriter )

Increases the video writer's internal reference count by one.

Parameters

[in] pVideoWriter A pointer to a video writer

Returns: The pointer passed via pDisplay

Remarks: If pVideoWriter is NULL, the function returns NULL. An error value is not set.

See also: ic4_videowriter_unref

◆ ic4_videowriter_unref()

void ic4_videowriter_unref ( struct IC4_VIDEO_WRITER * pVideoWriter )

Decreases the video writer's internal reference count by one.

If the reference count reaches zero, the object is destroyed.

Parameters

[in] pVideoWriter A pointer to a video writer

Remarks: If pVideoWriter is NULL, the function does nothing. An error value is not set.

See also: ic4_videowriter_ref