API Definitions

wz_codec_build_config

const char* wz_codec_build_config(void);
  • Returns a printable string containing an encoded version of the build configuration. This may be useful to support applications or debugging.
  • Return Value: A pointer to a constant string with the build configuration.

wz_codec_control

wz_codec_err_t wz_codec_control(wz_codec_ctx_t *ctx, int ctrl_id, ...);

Algorithm Control: wz_codec_control takes a context, a control ID, and a third parameter (with varying type). If the context is non-null and an error occurs, ctx->err will be set to the same value as the return value.

  • Provides control over various codec behaviors. Accepts a context, control ID, and additional parameters.
  • Return Value: Returns error code or success status.
    • WZ_CODEC_OK: The control request was processed successfully.
    • WZ_CODEC_ERROR: The control request failed to process.
    • WZ_CODEC_INVALID_PARAM: Invalid control ID or parameter was passed.
  • Parameters:
    • ctx: Pointer to the codec context.
    • ctrl_id: Algorithm-specific control ID (must be non-zero).
    • ...: Additional parameters depending on the control ID.

For a list of all the options that can be used, please refer to the "API Parameters" page.

wz_codec_destroy

wz_codec_err_t wz_codec_destroy(wz_codec_ctx_t *ctx);
  • Destroy a codec instance. Destroys a codec context, freeing any associated memory buffers.
  • Return Value:
    • WZ_CODEC_OK: The codec instance has been destroyed.
    • WZ_CODEC_INVALID_PARAM: ctx is a null pointer.
    • WZ_CODEC_ERROR: Codec context was not initialized.
  • Parameters:
    • ctx: Pointer to this instance's context.

wz_codec_err_to_string

const char* wz_codec_err_to_string(wz_codec_err_t err);

Converts an error number to a printable string.

Returns a human readable string for the last error returned by the algorithm. The returned error will be one line and will not contain any newline characters.

  • Return Value: A human-readable string representing the last error returned by the algorithm. The string will be one line and will not contain any newline characters.
  • Parameters:
    • err: The error number to be converted.

wz_codec_error

const char* wz_codec_error(const wz_codec_ctx_t *ctx);

  • Retrieves an error synopsis for a codec context. Returns a human readable string for the last error returned by the algorithm. The returned error will be one line and will not contain any newline characters.

  • Return Value: A human-readable string representing the last error returned by the algorithm. The string will be one line and will not contain any newline characters.

  • Parameters:
    • ctx: Pointer to the codec context instance.

wz_codec_error_detail

const char* wz_codec_error_detail(const wz_codec_ctx_t *ctx);

  • Retrieve detailed error information for codec context. Returns a human readable string providing detailed information about the last error. The returned string is only valid until the next wz_codec_* function call (except wz_codec_error and wz_codec_error_detail) on the codec context.

  • Return Value: A human-readable string providing detailed information about the last error. The returned string is only valid until the next wz_codec_* function call (except wz_codec_error and wz_codec_error_detail) on the codec context.

    • NULL: No detailed information is available.
  • Parameters:
    • ctx: Pointer to this instance's context.

wz_codec_get_caps

wz_codec_caps_t wz_codec_get_caps(wz_codec_iface_t *iface);
  • Get the capabilities of an algorithm. Retrieves the capabilities bitfield from the algorithm's interface.
  • Return Value: The bitfield representing the algorithm's capabilities.
  • Parameters:
    • iface: Pointer to the algorithm interface.

wz_codec_iface_name

const char* wz_codec_iface_name(wz_codec_iface_t *iface);

  • Return the name for a given interface. Returns a human readable string for name of the given codec interface.

  • Return Value: A human-readable string representing the name of the codec interface.

  • Parameters:
    • iface: Pointer to the codec interface.

wz_codec_get_option

wz_codec_err_t wz_codec_get_option(wz_codec_ctx_t *ctx, const char *name, char *buf, int *buf_sz);

  • wz_codec_get_option() takes a context, a key (option name), a buf pointer and an integer pointer. If the context is non-null and an error occurs, ctx->err will be set to the same value as the return value.

  • Return Value:

    • -1: The provided buffer is too small, and the required buffer size is written to *buf_sz.
    • WZ_CODEC_OK: The value of the option was successfully retrieved.
    • WZ_CODEC_INVALID_PARAM: The data provided was not valid.
    • WZ_CODEC_ERROR: The option was not successfully retrieved.
  • Parameters:
    • ctx: Pointer to this instance's context.
    • name: The name of the option (key).
    • buf: A pointer to a character buffer where the retrieved value will be stored. The buffer must be pre-allocated.
    • buf_sz: A pointer to an integer that holds the size of the provided buffer. If the buffer is too small, the function will return the required size (including null terminator).

For a list of all the options that can be used, please refer to the "API Parameters" page.

wz_codec_set_option

wz_codec_err_t wz_codec_set_option(wz_codec_ctx_t *ctx, const char *name, const char *value);

  • wz_codec_set_option() takes a context, a key (option name) and a value. If the context is non-null and an error occurs, ctx->err will be set to the same value as the return value.

  • Return Value:

    • WZ_CODEC_OK: The value of the option was set.
    • WZ_CODEC_INVALID_PARAM: The data provided was not valid.
    • WZ_CODEC_ERROR: The option was not successfully set.
  • Parameters:
    • ctx: Pointer to this instance's context.
    • name: The name of the option (key).
    • value: The value of the option.

For a list of all the options that can be used, please refer to the "API Parameters" page.

wz_codec_version

int wz_codec_version(void);
  • Return the version information (as an integer). Returns a packed encoding of the library version number. This will only include the major.minor.patch component of the version number. Note that this encoded value should be accessed through the macros provided, as the encoding may change in the future.
  • Return Value: The encoded version number.

wz_codec_version_extra_str

const char* wz_codec_version_extra_str(void);
  • Return the version information (as a string). Returns a printable "extra string". This is the component of the string returned by wz_codec_version_str() following the three digit version number.
  • Return Value: A string with additional version information.

wz_codec_version_str

const char* wz_codec_version_str(void);
  • Returns a printable string containing the full library version number. This may contain additional text following the three digit version number, as to indicate release candidates, pre-release versions, etc.
  • Return Value: A string containing the version number and possibly extra version information.

wz_obu_type_to_string

const char* wz_obu_type_to_string(WZ_OBU_TYPE type);
  • Returns string representation of WZ_OBU_TYPE.
  • Return Value: A string representing the given WZ_OBU_TYPE.
  • Parameters:
    • type: The WZ_OBU_TYPE to convert.

wz_codec_av1_cx

wz_codec_iface_t* wz_codec_av1_cx(void);
  • Provides the interface to the AV1 encoder.
  • Return Value: A pointer to the AV1 codec interface.

wz_codec_enc_config_default

wz_codec_err_t wz_codec_enc_config_default(wz_codec_iface_t *iface, wz_codec_enc_cfg_t *cfg, unsigned int usage);
  • Initializes an encoder configuration structure with default values. Supports the notion of "usages" so that an algorithm may offer different default settings depending on the user's intended goal. This function SHOULD be called by all applications to initialize the configuration structure before specializing the configuration with application specific values.
  • Return Value:
    • WZ_CODEC_OK: The configuration was populated successfully.
    • WZ_CODEC_INCAPABLE: The interface is not an encoder interface.
    • WZ_CODEC_INVALID_PARAM: A parameter was NULL, or the usage value was not recognized.
  • Parameters:
    • iface: Pointer to the algorithm interface to use.
    • cfg: Configuration buffer to populate.
    • usage: Algorithm-specific usage value. For AV1, this must be set to one of WZ_USAGE_GOOD_QUALITY (0), WZ_USAGE_REALTIME (1), or WZ_USAGE_ALL_INTRA (2).

wz_codec_enc_config_set

wz_codec_err_t wz_codec_enc_config_set(wz_codec_ctx_t *ctx, const wz_codec_enc_cfg_t *cfg);
  • Reconfigures an encoder instance according to the given configuration.
  • Return Value:
    • WZ_CODEC_OK: The configuration was populated successfully.
    • WZ_CODEC_INCAPABLE: The interface is not an encoder interface.
    • WZ_CODEC_INVALID_PARAM: A parameter was NULL, or the usage value was not recognized.
  • Parameters:
    • ctx: Pointer to this instance's context.
    • cfg: Configuration buffer to use.

wz_codec_enc_init_ver

wz_codec_err_t wz_codec_enc_init_ver(wz_codec_ctx_t *ctx, wz_codec_iface_t *iface, const wz_codec_enc_cfg_t *cfg, wz_codec_flags_t flags, int ver);

Initialize an encoder instance.

Initializes an encoder context using the given interface.

NOTE: Applications should call the wz_codec_enc_init convenience macro instead of this function directly, to ensure that the ABI version number parameter is properly initialized.

If the library was configured with -DCONFIG_MULTITHREAD=0, this call is not thread safe and should be guarded with a lock if being used in a multithreaded context.

If wz_codec_enc_init_ver() fails, it is not necessary to call wz_codec_destroy() on the encoder context.

  • Return Value:
    • WZ_CODEC_OK: The encoder algorithm was initialized successfully.
    • WZ_CODEC_MEM_ERROR: Memory allocation failed.
  • Parameters:
    • ctx: Pointer to this instance's context.
    • iface: Pointer to the algorithm interface to use.
    • cfg: Configuration to use, if known.
    • flags: Bitfield of WZ_CODEC_USE_* flags.
    • ver: ABI version number. Must be set to WZ_ENCODER_ABI_VERSION.

NOTE: For a list of all the options that can be used, please refer to the "API Parameters" page.

wz_codec_encode

wz_codec_err_t wz_codec_encode(wz_codec_ctx_t *ctx, wz_image_t *img, wz_codec_pts_t pts, unsigned long duration, wz_enc_frame_flags_t flags);

Encode a frame.

Encodes a video frame at the given "presentation time." The presentation time stamp (PTS) MUST be strictly increasing.

When the last frame has been passed to the encoder, this function should continue to be called in a loop, with the img parameter set to NULL. This will signal the end-of-stream condition to the encoder and allow it to encode any held buffers. Encoding is complete when wz_codec_encode() is called with img set to NULL and wz_codec_get_cx_data() returns no data.

  • Return Value:
    • WZ_CODEC_OK: The frame was encoded successfully.
    • WZ_CODEC_INCAPABLE: The interface is not an encoder interface.
    • WZ_CODEC_INVALID_PARAM: A parameter was NULL, the image format is unsupported, or other validation errors occurred.
  • Parameters:
    • ctx: Pointer to this instance's context.
    • img: Image data to encode, or NULL to flush.
    • pts: Presentation time stamp, in timebase units. Ignored if img is NULL.
    • duration: Duration to show the frame, in timebase units. Must be nonzero if img is not NULL. Ignored if img is NULL.
    • flags: Flags for encoding the frame.

wz_codec_get_cx_data

const wz_codec_cx_pkt_t* wz_codec_get_cx_data(wz_codec_ctx_t *ctx, wz_codec_iter_t *iter);

Encoded data iterator.

Iterates over a list of data packets to be passed from the encoder to the application. The different kinds of packets available are enumerated in wz_codec_cx_pkt_kind.

WZ_CODEC_CX_FRAME_PKT packets should be passed to the application's muxer. Multiple compressed frames may be in the list. WZ_CODEC_STATS_PKT packets should be appended to a global buffer.

The application MUST silently ignore any packet kinds that it does not recognize or support.

The data buffers returned from this function are only guaranteed to be valid until the application makes another call to any wz_codec_* function.

  • Return Value: A pointer to an output data packet (compressed frame, statistics, etc.) or NULL to signal the end of the list.
  • Parameters:
    • ctx: Pointer to this instance's context.
    • iter: Iterator storage, initialized to NULL.

wz_codec_get_global_headers

wz_fixed_buf_t* wz_codec_get_global_headers(wz_codec_ctx_t *ctx);

Get global stream headers.

Retrieves a stream level global header packet, if supported by the codec. Calls to this function should be deferred until all configuration information has been passed to the codec. Otherwise the global header data may be invalidated by additional configuration changes.

The AV1 implementation of this function returns an OBU. The OBU returned is in Low Overhead Bitstream Format. Specifically, the obu_has_size_field bit is set, and the buffer contains the obu_size field for the returned OBU.

  • Return Value:
    • NULL: The encoder does not support global headers, or an error occurred while generating the header.
    • Non-NULL: Pointer to a buffer containing the global header packet. The caller must free the memory using free().
  • Parameters:
    • ctx: Pointer to this instance's context.

wz_codec_get_preview_frame

const wz_image_t* wz_codec_get_preview_frame(wz_codec_ctx_t *ctx);

Returns an image that can be used as a preview. Shows the image as it would exist at the decompressor. The application MUST NOT write into this image buffer.

  • Return Value: A pointer to a preview image, or NULL if no image is available.
  • Parameters:
    • ctx: Pointer to this instance's context.

wz_codec_set_cx_data_buf

wz_codec_err_t wz_codec_set_cx_data_buf(wz_codec_ctx_t *ctx, const wz_fixed_buf_t *buf, unsigned int pad_before, unsigned int pad_after);

Set compressed data output buffer.

  • Sets the buffer that the codec should output the compressed data into. This call effectively sets the buffer pointer returned in the next WZ_CODEC_CX_FRAME_PKT packet. Subsequent packets will be appended into this buffer. The buffer is preserved across frames, so applications must periodically call this function after flushing the accumulated compressed data to disk or to the network to reset the pointer to the buffer's head.
  • pad_before bytes will be skipped before writing the compressed data, and pad_after bytes will be appended to the packet. The size of the packet will be the sum of the size of the actual compressed data, pad_before, and pad_after. The padding bytes will be preserved (not overwritten).
  • Note that calling this function does not guarantee that the returned compressed data will be placed into the specified buffer. In the event that the encoded data will not fit into the buffer provided, the returned packet MAY point to an internal buffer, as it would if this call were never used. In this event, the output packet will NOT have any padding, and the application must free space and copy it to the proper place. This is of particular note in configurations that may output multiple packets for a single encoded frame (e.g., lagged encoding) or if the application does not reset the buffer periodically.
  • Applications may restore the default behavior of the codec providing the compressed data buffer by calling this function with a NULL buffer.

  • Applications MUST NOT call this function during iteration of wz_codec_get_cx_data().

  • Return Value:

    • WZ_CODEC_OK: The buffer was set successfully.
    • WZ_CODEC_INVALID_PARAM: A parameter was NULL, the image format is unsupported, etc.
  • Parameters:
    • ctx: Pointer to this instance's context.
    • buf: Buffer to store compressed data into.
    • pad_before: Bytes to skip before writing compressed data.
    • pad_after: Bytes to skip after writing compressed data.

wz_img_add_metadata

int wz_img_add_metadata(wz_image_t *img, uint32_t type, const uint8_t *data, size_t sz, wz_metadata_insert_flags_t insert_flag);
  • Add metadata to image.

  • Adds metadata to wz_image_t. Function makes a copy of the provided data parameter. Metadata insertion point is controlled by insert_flag.

  • Return Value: Returns 0 on success. If img or data is NULL, sz is 0, or memory allocation fails, it returns -1.

  • Parameters:
    • img: Image descriptor.
    • type: Metadata type.
    • data: Metadata contents.
    • sz: Metadata contents size.
    • insert_flag: Metadata insert flag.

wz_img_alloc

wz_image_t* wz_img_alloc(wz_image_t *img, wz_img_fmt_t fmt, unsigned int d_w, unsigned int d_h, unsigned int align);
  • Open a descriptor, allocating storage for the underlying image.

  • Returns a descriptor for storing an image of the given format. The storage for the image is allocated on the heap.

  • Return Value: Returns a pointer to the initialized image descriptor. If the img parameter is non-null, the value of the img parameter will be returned.

  • Parameters:
    • img: Pointer to storage for descriptor. If this parameter is NULL, the storage for the descriptor will be allocated on the heap.
    • fmt: Format for the image.
    • d_w: Width of the image.
    • d_h: Height of the image.
    • align: Alignment, in bytes, of the image buffer and each row in the image (stride).

wz_img_alloc_with_border

wz_image_t* wz_img_alloc_with_border(wz_image_t *img, wz_img_fmt_t fmt, unsigned int d_w, unsigned int d_h, unsigned int align, unsigned int size_align, unsigned int border);
  • Open a descriptor, allocating storage for the underlying image with a border.

  • Returns a descriptor for storing an image of the given format and its borders. The storage for the image is allocated on the heap.

  • Return Value: Returns a pointer to the initialized image descriptor. If the img parameter is non-null, the value of the img parameter will be returned.

  • Parameters:
    • img: Pointer to storage for descriptor. If this parameter is NULL, the storage for the descriptor will be allocated on the heap.
    • fmt: Format for the image.
    • d_w: Width of the image.
    • d_h: Height of the image.
    • align: Alignment, in bytes, of the image buffer and each row in the image (stride).
    • size_align: Alignment, in pixels, of the image width and height.
    • border: A border that is padded on four sides of the image.

wz_img_flip

void wz_img_flip(wz_image_t *img);
  • Flip the image vertically (top for bottom).

  • Adjusts the image descriptor's pointers and strides to make the image be referenced upside-down.

  • Parameters:

    • img: Image descriptor.

wz_img_free

void wz_img_free(wz_image_t *img);
  • Close an image descriptor.

  • Frees all allocated storage associated with an image descriptor.

  • Parameters:

    • img: Image descriptor.

wz_img_get_metadata

const wz_metadata_t* wz_img_get_metadata(const wz_image_t *img, size_t index);
  • Return a metadata payload stored within the image metadata array.

  • Gets the metadata (wz_metadata_t) at the indicated index in the image metadata array.

  • Return Value: Returns a const pointer to the selected metadata. If img and/or index is invalid, it returns NULL.

  • Parameters:
    • img: Pointer to image descriptor to get metadata from.
    • index: Metadata index to get from metadata array.

wz_img_metadata_alloc

wz_metadata_t* wz_img_metadata_alloc(uint32_t type, const uint8_t *data, size_t sz, wz_metadata_insert_flags_t insert_flag);
  • Allocate memory for wz_metadata struct.

  • Allocates storage for the metadata payload, sets its type, and copies the payload data into the wz_metadata struct. A metadata payload buffer of size sz is allocated, and sz bytes are copied from data into the payload buffer.

  • Return Value: Returns the newly allocated wz_metadata struct. If data is NULL, sz is 0, or memory allocation fails, it returns NULL.

  • Parameters:
    • type: Metadata type.
    • data: Metadata data pointer.
    • sz: Metadata size.
    • insert_flag: Metadata insert flag.

wz_img_metadata_free

void wz_img_metadata_free(wz_metadata_t *metadata);
  • Free metadata struct.

  • Free metadata struct and its buffer.

  • Parameters:

    • metadata: Metadata struct pointer.

wz_img_num_metadata

size_t wz_img_num_metadata(const wz_image_t *img);
  • Return the number of metadata blocks within the image.

  • Gets the number of metadata blocks contained within the provided image metadata array.

  • Return Value: Returns the size of the metadata array. If img or metadata is NULL, it returns 0.

  • Parameters:
    • img: Pointer to image descriptor to get metadata number from.

wz_img_plane_height

int wz_img_plane_height(const wz_image_t *img, int plane);
  • Get the height of a plane.

  • Get the height of a plane of an image.

  • Parameters:

    • img: Image descriptor.
    • plane: Plane index.

wz_img_plane_width

int wz_img_plane_width(const wz_image_t *img, int plane);
  • Get the width of a plane.

  • Get the width of a plane of an image.

  • Parameters:

    • img: Image descriptor.
    • plane: Plane index.

wz_img_remove_metadata

void wz_img_remove_metadata(wz_image_t *img);
  • Remove metadata from image.

  • Removes all metadata in the image metadata list and sets the metadata list pointer to NULL.

  • Parameters:

    • img: Image descriptor.

wz_img_set_rect

int wz_img_set_rect(wz_image_t *img, unsigned int x, unsigned int y, unsigned int w, unsigned int h, unsigned int border);
  • Set the rectangle identifying the displayed portion of the image.

  • Updates the displayed rectangle (aka viewport) on the image surface to match the specified coordinates and size. Specifically, sets img->d_w, img->d_h, and elements of the img->planes[] array.

  • Return Value: 0 if the requested rectangle is valid, nonzero (-1) otherwise.

  • Parameters:
    • img: Image descriptor.
    • x: Leftmost column.
    • y: Topmost row.
    • w: Width.
    • h: Height.
    • border: A border that is padded on four sides of the image.

wz_img_wrap

wz_image_t* wz_img_wrap(wz_image_t *img, wz_img_fmt_t fmt, unsigned int d_w, unsigned int d_h, unsigned int align, unsigned char *img_data);
  • Open a descriptor, using existing storage for the underlying image.

  • Returns a descriptor for storing an image of the given format. The storage for the image has been allocated elsewhere, and a descriptor is desired to "wrap" that storage.

  • Return Value: Returns a pointer to the initialized image descriptor. If the img parameter is non-null, the value of the img parameter will be returned.

  • Parameters:
    • img: Pointer to storage for descriptor. If this parameter is NULL, the storage for the descriptor will be allocated on the heap.
    • fmt: Format for the image.
    • d_w: Width of the image.
    • d_h: Height of the image.
    • align: Alignment, in bytes, of each row in the image (stride).
    • img_data: Storage to use for the image.