The Codec provides functions for codec devices.

Required Header

#include <hal-codec.h>

Overview

The codec devices have various specifications and backend interfaces, so it's hard to control them using single code. The codec HAL provides common abstraction interfaces to control codec devices which are different.

Key functionalities include:

Configure and release codec devices
Decode or encode image

State Diagram

State Transitions

FUNCTION	PRE-STATE	POST-STATE	SYNC TYPE
hal_codec_init()	N/A	INITIALIZED	SYNC
hal_codec_deinit()	INITIALIZED	N/A	SYNC
hal_codec_configure()	INITIALIZED	CONFIGURED	SYNC
hal_codec_release()	CONFIGURED	INITIALIZED	SYNC
hal_codec_start()	CONFIGURED	STARTED	SYNC
hal_codec_stop()	STARTED	CONFIGURED	SYNC

For more information on the Codec features and the macros, see HAL Codec programming guides and tutorials.

Typedefs
typedef int(*	hal_codec_message_cb )(hal_codec_message_s message, void user_data)
	Callback function for notification from codec HAL.
typedef struct _hal_backend_codec_funcs	hal_backend_codec_funcs
	The structure type of the codec HAL functions.
Defines
#define	HAL_CODEC_BUFFER_PLANE_MAX 4
	The maximum number of planes in buffer.
#define	HAL_CODEC_CAPABILITY_MAX 8
	The maximum number of codec capability.
#define	HAL_CODEC_CAPABILITY_FORMAT_MAX 4
	The maximum number of codec capability format.
#define	HAL_CODEC_CAPABILITY_FEATURE_MAX 16
	The maximum number of codec capability feature.
#define	HAL_CODEC_FEATURE_LENGTH 16
	The length of codec capability feature.

Data Structure Documentation

struct hal_codec_resolution_s

The structure type of the resolution.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
int	width
int	height

Field Documentation

int hal_codec_resolution_s::height

The height of resolution

int hal_codec_resolution_s::width

The width of resolution

struct hal_codec_plane_s

The structure type of the buffer plane.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
unsigned char *	data
uint32_t	stride
uint32_t	size
uint32_t	bytesused

Field Documentation

uint32_t hal_codec_plane_s::bytesused

The actual data size of plane

unsigned char* hal_codec_plane_s::data

The data pointer of plane, it could be NULL when it's secure buffer

uint32_t hal_codec_plane_s::size

The size of plane

uint32_t hal_codec_plane_s::stride

The stride of plane

struct hal_codec_planes_s

The structure type of the buffer planes.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
uint32_t	num_planes
hal_codec_plane_s	plane [4]

Field Documentation

uint32_t hal_codec_planes_s::num_planes

The number of planes

hal_codec_plane_s hal_codec_planes_s::plane[4]

The array of planes

struct hal_codec_memory_s

The structure type of the buffer memory.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
uint32_t	num_fd
int	fd [4]

Field Documentation

int hal_codec_memory_s::fd[4]

The fd

uint32_t hal_codec_memory_s::num_fd

The number of fd

struct hal_codec_meta_s

The structure type of the buffer meta.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
hal_codec_format_e	format
hal_codec_resolution_s	resolution
hal_codec_rotation_e	rotation
uint64_t	timestamp
uint32_t	duration
uint32_t	flags

Field Documentation

uint32_t hal_codec_meta_s::duration

The duration

uint32_t hal_codec_meta_s::flags

The flags

hal_codec_format_e hal_codec_meta_s::format

The format

hal_codec_resolution_s hal_codec_meta_s::resolution

The resolution of frame

hal_codec_rotation_e hal_codec_meta_s::rotation

The rotation of frame

uint64_t hal_codec_meta_s::timestamp

The timestamp

struct hal_codec_buffer_s

The structure type of the buffer.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
int	index
uint32_t	size
hal_codec_planes_s	planes
hal_codec_memory_s	memory
hal_codec_meta_s	meta

Field Documentation

int hal_codec_buffer_s::index

The index of buffer

hal_codec_memory_s hal_codec_buffer_s::memory

The memory of buffer for zero copy

hal_codec_meta_s hal_codec_buffer_s::meta

The meta data of buffer

hal_codec_planes_s hal_codec_buffer_s::planes

The planes of buffer - logical plane data

uint32_t hal_codec_buffer_s::size

The size of buffer

struct hal_codec_custom_command_s

The structure type of the codec HAL custom command.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
const char *	name
void *	value

Field Documentation

const char* hal_codec_custom_command_s::name

The name of custom command

void* hal_codec_custom_command_s::value

The value of custom command

struct hal_codec_batch_command_control_s

The structure type of the codec HAL batch command.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
uint64_t	command_set_flag
uint64_t	bitrate
hal_codec_custom_command_s	custom

Field Documentation

uint64_t hal_codec_batch_command_control_s::bitrate

The value for bitrate command

uint64_t hal_codec_batch_command_control_s::command_set_flag

The flag for updating commands

hal_codec_custom_command_s hal_codec_batch_command_control_s::custom

The value for custom command

struct hal_codec_message_s

The structure type of the codec HAL message.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
hal_codec_message_type_e	type
hal_codec_error_e	error_code
hal_codec_buffer_s *	buffer
hal_codec_resolution_s	resolution

Field Documentation

hal_codec_buffer_s* hal_codec_message_s::buffer

The buffer for HAL_CODEC_MESSAGE_TYPE_INPUT_BUFFER_USED or HAL_CODEC_MESSAGE_TYPE_OUTPUT_BUFFER

hal_codec_error_e hal_codec_message_s::error_code

The error code

hal_codec_resolution_s hal_codec_message_s::resolution

The changed resolution

hal_codec_message_type_e hal_codec_message_s::type

The type of message

struct hal_codec_capability_feature_s

The structure type of the codec capability feature.

Since:: HAL_MODULE_CODEC 1.2

Data Fields
uint32_t	count
char	value [16][16]

Field Documentation

uint32_t hal_codec_capability_feature_s::count

The count of feature

char hal_codec_capability_feature_s::value[16][16]

The value of feature

struct hal_codec_capability_base_s

The structure type of the codec capability base.

Since:: HAL_MODULE_CODEC 1.2

Data Fields
hal_codec_capability_feature_s	alignment
hal_codec_capability_feature_s	stream_format
hal_codec_capability_feature_s	level
hal_codec_capability_feature_s	profile
hal_codec_resolution_s	max_resolution

Field Documentation

hal_codec_capability_feature_s hal_codec_capability_base_s::alignment

The alignment

hal_codec_capability_feature_s hal_codec_capability_base_s::level

The level

hal_codec_resolution_s hal_codec_capability_base_s::max_resolution

The max resolution

hal_codec_capability_feature_s hal_codec_capability_base_s::profile

The profile

hal_codec_capability_feature_s hal_codec_capability_base_s::stream_format

The stream format

struct hal_codec_capability_decoder_s

The structure type of the codec capability for decoder.

Since:: HAL_MODULE_CODEC 1.2

Data Fields
hal_codec_capability_base_s	base
hal_codec_format_e	in_format
uint32_t	out_format_count
hal_codec_format_e	out_format [4]

Field Documentation

hal_codec_capability_base_s hal_codec_capability_decoder_s::base

The base capability

hal_codec_format_e hal_codec_capability_decoder_s::in_format

The input format

hal_codec_format_e hal_codec_capability_decoder_s::out_format[4]

The output format array

uint32_t hal_codec_capability_decoder_s::out_format_count

The output format count

struct hal_codec_capability_encoder_s

The structure type of the codec capability for encoder.

Since:: HAL_MODULE_CODEC 1.2

Data Fields
hal_codec_capability_base_s	base
uint32_t	in_format_count
hal_codec_format_e	in_format [4]
hal_codec_format_e	out_format

Field Documentation

hal_codec_capability_base_s hal_codec_capability_encoder_s::base

The base capability

hal_codec_format_e hal_codec_capability_encoder_s::in_format[4]

The input format array

uint32_t hal_codec_capability_encoder_s::in_format_count

The input format count

hal_codec_format_e hal_codec_capability_encoder_s::out_format

The output format

struct hal_codec_capability_s

The structure type of the codec capability.

Since:: HAL_MODULE_CODEC 1.2

Data Fields
uint32_t	decoder_count
hal_codec_capability_decoder_s	decoder [8]
uint32_t	encoder_count
hal_codec_capability_encoder_s	encoder [8]

Field Documentation

hal_codec_capability_decoder_s hal_codec_capability_s::decoder[8]

The capability for decoder

uint32_t hal_codec_capability_s::decoder_count

The count of capability for decoder

hal_codec_capability_encoder_s hal_codec_capability_s::encoder[8]

The capability for encoder

uint32_t hal_codec_capability_s::encoder_count

The count of capability for encoder

struct _hal_backend_codec_funcs

The structure type of the codec HAL functions.

Since:: HAL_MODULE_CODEC 1.0

Data Fields
int(*	init )(hal_codec_type_e type, void **codec_handle)
int(*	deinit )(void *codec_handle)
int(*	configure )(void *codec_handle, int width, int height, hal_codec_format_e in_format, hal_codec_format_e out_format, bool is_secure)
int(*	release )(void *codec_handle)
int(*	start )(void codec_handle, hal_codec_message_cb callback, void user_data)
int(*	stop )(void *codec_handle)
int(*	flush )(void *codec_handle)
int(*	decode )(void codec_handle, hal_codec_buffer_s buffer)
int(*	encode )(void codec_handle, hal_codec_buffer_s buffer)
int(*	release_output_buffer )(void *codec_handle, int buffer_index)
int(*	get_state )(void codec_handle, hal_codec_state_e state)
int(*	set_command )(void codec_handle, hal_codec_command_e command, void value)
int(*	get_command )(void codec_handle, hal_codec_command_e command, void *value)
int(*	set_batch_command )(void codec_handle, hal_codec_batch_command_control_s batch_command, hal_codec_command_e *error_command)
int(*	get_capability )(hal_codec_capability_s *capability)

Field Documentation

int(* _hal_backend_codec_funcs::configure)(void *codec_handle, int width, int height, hal_codec_format_e in_format, hal_codec_format_e out_format, bool is_secure)

Configure codec

int(* _hal_backend_codec_funcs::decode)(void *codec_handle, hal_codec_buffer_s *buffer)

Decode data

int(* _hal_backend_codec_funcs::deinit)(void *codec_handle)

Deinitialize HAL backend handle

int(* _hal_backend_codec_funcs::encode)(void *codec_handle, hal_codec_buffer_s *buffer)

Encode data

int(* _hal_backend_codec_funcs::flush)(void *codec_handle)

Flush codec

int(* _hal_backend_codec_funcs::get_capability)(hal_codec_capability_s *capability)

Get capability of codec (Since 1.2)

int(* _hal_backend_codec_funcs::get_command)(void *codec_handle, hal_codec_command_e command, void **value)

Get command for various settings

int(* _hal_backend_codec_funcs::get_state)(void *codec_handle, hal_codec_state_e *state)

Get state of codec

int(* _hal_backend_codec_funcs::init)(hal_codec_type_e type, void **codec_handle)

Initialize HAL backend handle

int(* _hal_backend_codec_funcs::release)(void *codec_handle)

Release codec

int(* _hal_backend_codec_funcs::release_output_buffer)(void *codec_handle, int buffer_index)

Release output buffer

int(* _hal_backend_codec_funcs::set_batch_command)(void *codec_handle, hal_codec_batch_command_control_s *batch_command, hal_codec_command_e *error_command)

Set batch command for multiple settings

int(* _hal_backend_codec_funcs::set_command)(void *codec_handle, hal_codec_command_e command, void *value)

Set command for various settings

int(* _hal_backend_codec_funcs::start)(void *codec_handle, hal_codec_message_cb callback, void *user_data)

Start codec

int(* _hal_backend_codec_funcs::stop)(void *codec_handle)

Stop codec

Define Documentation

#define HAL_CODEC_BUFFER_PLANE_MAX 4

The maximum number of planes in buffer.

Since:: HAL_MODULE_CODEC 1.0

#define HAL_CODEC_CAPABILITY_FEATURE_MAX 16

The maximum number of codec capability feature.

Since:: HAL_MODULE_CODEC 1.2

#define HAL_CODEC_CAPABILITY_FORMAT_MAX 4

The maximum number of codec capability format.

Since:: HAL_MODULE_CODEC 1.2

#define HAL_CODEC_CAPABILITY_MAX 8

The maximum number of codec capability.

Since:: HAL_MODULE_CODEC 1.2

#define HAL_CODEC_FEATURE_LENGTH 16

The length of codec capability feature.

Since:: HAL_MODULE_CODEC 1.2

Typedef Documentation

typedef struct _hal_backend_codec_funcs hal_backend_codec_funcs

The structure type of the codec HAL functions.

Since:: HAL_MODULE_CODEC 1.0

typedef int(* hal_codec_message_cb)(hal_codec_message_s *message, void *user_data)

Callback function for notification from codec HAL.

Since:: HAL_MODULE_CODEC 1.0

Parameters:

[in]	message	The message from codec HAL
[in]	user_data	The user data for callback

See also:: hal_codec_add_message_callback(); hal_codec_remove_message_callback()

Enumeration Type Documentation

enum hal_codec_buffer_flag_e

Enumeration for the buffer flag.

Since:: HAL_MODULE_CODEC 1.0

Enumerator:

HAL_CODEC_BUFFER_FLAG_NONE	None flag
HAL_CODEC_BUFFER_FLAG_CODECCONFIG	Codec config flag
HAL_CODEC_BUFFER_FLAG_SYNCFRAME	Sync frame flag
HAL_CODEC_BUFFER_FLAG_EOS	EOS(End of stream) flag
HAL_CODEC_BUFFER_FLAG_ROTATED	Rotated flag
HAL_CODEC_BUFFER_FLAG_SECURE	Secure flag

enum hal_codec_command_e

Enumeration for the codec HAL command.

Since:: HAL_MODULE_CODEC 1.0

Enumerator:

HAL_CODEC_COMMAND_BASE	Base of command
HAL_CODEC_COMMAND_BITRATE	Bitrate
HAL_CODEC_COMMAND_REQUEST_CODECDATA	Request codec data
HAL_CODEC_COMMAND_REQUEST_SYNCFRAME	Request syncframe
HAL_CODEC_COMMAND_CUSTOM	Custom

enum hal_codec_error_e

Enumeration for the codec HAL error.

Since:: HAL_MODULE_CODEC 1.0

Enumerator:

HAL_CODEC_ERROR_NONE	Error none
HAL_CODEC_ERROR_NOT_SUPPORTED	Not supported
HAL_CODEC_ERROR_PERMISSION_DENIED	Permission denied
HAL_CODEC_ERROR_INVALID_PARAMETER	Invalid parameter
HAL_CODEC_ERROR_INVALID_STATE	Invalid state
HAL_CODEC_ERROR_OUT_OF_MEMORY	Out of memory
HAL_CODEC_ERROR_DEVICE_OPEN	Device open
HAL_CODEC_ERROR_DEVICE_NOT_FOUND	Device not found
HAL_CODEC_ERROR_DEVICE_UNAVAILABLE	Device unavailable
HAL_CODEC_ERROR_DEVICE_READ	Device read
HAL_CODEC_ERROR_DEVICE_WRITE	Device write
HAL_CODEC_ERROR_DEVICE_BUSY	Device busy
HAL_CODEC_ERROR_DEVICE_TIME_OUT	Device time out
HAL_CODEC_ERROR_INTERNAL	Internal
HAL_CODEC_ERROR_NOT_IMPLEMENTED	Not implemented
HAL_CODEC_ERROR_UNKNOWN	Unknown

enum hal_codec_format_e

Enumeration for the codec HAL format.

Since:: HAL_MODULE_CODEC 1.0

Enumerator:

HAL_CODEC_FORMAT_H264	Encoded - H.264
HAL_CODEC_FORMAT_H265	Encoded - H.265
HAL_CODEC_FORMAT_H266	Encoded - H.266
HAL_CODEC_FORMAT_VP8	Encoded - VP8
HAL_CODEC_FORMAT_VP9	Encoded - VP9
HAL_CODEC_FORMAT_AV1	Encoded - AV1
HAL_CODEC_FORMAT_MJPEG	Encoded - MotionJPEG (Since 1.1)
HAL_CODEC_FORMAT_NV12	RAW - NV12
HAL_CODEC_FORMAT_NV12T	RAW - NV12 Tiled
HAL_CODEC_FORMAT_NV21	RAW - NV21
HAL_CODEC_FORMAT_I420	RAW - I420(YU12)
HAL_CODEC_FORMAT_YV12	RAW - YV12
HAL_CODEC_FORMAT_YUYV	RAW - YUYV
HAL_CODEC_FORMAT_UYVY	RAW - UYVY
HAL_CODEC_FORMAT_BGRA8888	RAW - BGRA8888
HAL_CODEC_FORMAT_ARGB8888	RAW - ARGB8888

enum hal_codec_format_type_e

Enumeration for codec HAL format type.

Since:: HAL_MODULE_CODEC 1.0

Enumerator:

HAL_CODEC_FORMAT_TYPE_ENCODED	Encoded format type
HAL_CODEC_FORMAT_TYPE_RAW	RAW format type

enum hal_codec_message_type_e

Enumeration for the codec HAL message type.

Since:: HAL_MODULE_CODEC 1.0

Enumerator:

HAL_CODEC_MESSAGE_TYPE_INPUT_BUFFER_USED	Input buffer is used
HAL_CODEC_MESSAGE_TYPE_OUTPUT_BUFFER	Output buffer is delivered
HAL_CODEC_MESSAGE_TYPE_RESOLUTION_CHANGED	Resolution is changed
HAL_CODEC_MESSAGE_TYPE_ERROR	Error is occurred

enum hal_codec_rotation_e

Enumeration for the buffer rotation.

Since:: HAL_MODULE_CODEC 1.0

Enumerator:

HAL_CODEC_ROTATION_NONE	None rotation
HAL_CODEC_ROTATION_90	90 degree rotation
HAL_CODEC_ROTATION_180	180 degree rotation
HAL_CODEC_ROTATION_270	270 degree rotation

enum hal_codec_state_e

Enumeration for the codec HAL state.

Since:: HAL_MODULE_CODEC 1.0

Enumerator:

HAL_CODEC_STATE_INITIALIZED	Initialized state
HAL_CODEC_STATE_CONFIGURED	Configured state
HAL_CODEC_STATE_STARTED	Started state

enum hal_codec_type_e

Enumeration for the codec HAL type.

Since:: HAL_MODULE_CODEC 1.0

Enumerator:

HAL_CODEC_TYPE_DECODER	Decoder type
HAL_CODEC_TYPE_ENCODER	Encoder type

Required Header

Overview

State Diagram

State Transitions

Typedefs

Defines

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Define Documentation

Typedef Documentation

Enumeration Type Documentation