Video Writer

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

Data Structures

struct   IC4_VIDEO_WRITER

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_WRITERic4_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

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]pVideoWriterA video writer that previously began writing a file
[in]bufferAn 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]pVideoWriterA video writer that previously began writing a file
[in]bufferAn 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]pVideoWriterA video writer
[in]file_nameName of the new video file
[in]image_typeImage type of the images that are going to be written
[in]frame_ratePlayback 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]typeSelects the type of video writer to create
[out]ppVideoWriterPointer 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]pVideoWriterA 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]pVideoWriterA video writer
[out]ppPropertyMapPointer 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]pVideoWriterA 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]pVideoWriterA 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