GMF Elements

[中文]

An element is the object in GMF-Core that carries concrete processing logic. Steps such as decoding, encoding, resampling, mixing, and image scaling are all integrated into the pipeline as elements; the pipeline is responsible for orchestrating connections, the task is responsible for scheduling element callbacks, and the element only implements its own initialization, processing, and resource cleanup logic.

For payload, port, and the acquire-release protocol, see Data Flow. For pipeline orchestration, task scheduling, lifecycle, and control interfaces, see GMF Pipeline and Task Scheduling. For the overall object relationships, see GMF-Core Overview.

Lifecycle and Object Structure

An element inherits from the object base class esp_gmf_obj_t, which provides tag, configuration data, copy, and destroy interfaces; the element base class esp_gmf_element_t adds lifecycle callback functions, input/output ports, capability description, runtime methods, and an event receiver interface.

An element must implement three main callback functions:

  • open: One-time resource initialization, such as creating algorithm handles, reading configuration, and computing internal parameters based on upstream format info.

  • process: Execute one data processing step, typically acquiring a payload from the input port, processing it, and writing to the output port.

  • close: Release resources allocated in the open phase. Regardless of whether the pipeline ends normally, is stopped, or encounters an error, the framework attempts to execute close for each opened element.

An element can also implement reset and event_receiver. The former resets internal state; the latter receives upstream format info, pipeline events, or application-side events. Elements that require upstream format info to open should set dependency = true in their configuration, so the pipeline registers their open/process jobs after receiving the REPORT_INFO event; for the flow, see the dependent element section in GMF Pipeline and Task Scheduling.

Based on media type, GMF-Core provides three derived element classes.

Derived Class

Format Info

Typical Fields

esp_gmf_audio_element_t

esp_gmf_info_sound_t

Sample rate, channels, bit depth, FourCC

esp_gmf_video_element_t

esp_gmf_info_video_t

Resolution, frame rate, FourCC

esp_gmf_pic_element_t

esp_gmf_info_pic_t

Width, height, FourCC

Port Attributes

At initialization, an element declares constraints on its input and output ports, including port count, buffer alignment, port type, and recommended data size per acquire. These constraints are described by esp_gmf_element_port_attr_t and are typically set via macros.

esp_gmf_element_cfg_t el_cfg = { 0 };

ESP_GMF_ELEMENT_IN_PORT_ATTR_SET(
    el_cfg.in_attr,
    ESP_GMF_EL_PORT_CAP_SINGLE,
    16,
    16,
    ESP_GMF_PORT_TYPE_BYTE,
    768);

ESP_GMF_ELEMENT_OUT_PORT_ATTR_SET(
    el_cfg.out_attr,
    ESP_GMF_EL_PORT_CAP_SINGLE,
    16,
    16,
    ESP_GMF_PORT_TYPE_BYTE,
    768);

ESP_GMF_EL_PORT_CAP_SINGLE means the port can only connect to one peer; ESP_GMF_EL_PORT_CAP_MULTI means multiple peers can share the port. For port type, payload ownership, and acquire-release call order, see Data Flow.

Capability Description

Capability description is the mechanism by which an element declares its capabilities externally. It is not a single format field, but a set of capability nodes that can be queried externally: each esp_gmf_cap_t identifies the capability category with cap_eightcc, and can carry performance info perf and an attribute iterator function attr_fun. Attributes are described by esp_gmf_cap_attr_t, supporting discrete values, step ranges, multiple ranges, and constant values. For EIGHTCC capability identifier definitions, see System Utilities; for media format FourCC definitions, see GMF FourCC.

An element lazily loads its capability list via ops.load_caps. The first time external code calls esp_gmf_element_get_caps(), the framework calls this callback and caches the result in the element object. A typical implementation:

static esp_gmf_err_t load_caps(esp_gmf_element_handle_t handle)
{
    esp_gmf_cap_t *caps = NULL;
    esp_gmf_cap_t cap = { 0 };

    cap.cap_eightcc = ESP_GMF_CAPS_VIDEO_SCALE;
    cap.attr_fun = scale_attr_iter;
    esp_gmf_cap_append(&caps, &cap);

    cap.cap_eightcc = ESP_GMF_CAPS_VIDEO_CROP;
    cap.attr_fun = crop_attr_iter;
    esp_gmf_cap_append(&caps, &cap);

    ESP_GMF_ELEMENT_GET(handle)->caps = caps;
    return ESP_GMF_ERR_OK;
}

Capability queries can occur during the pool phase or after the pipeline is built. Applications or upper-layer wrappers first iterate element templates in the pool, then read each element’s capability description, and select suitable elements by capability category or attribute range. For example, a video pipeline can find elements with scaling, cropping, and rotation capabilities via cap_eightcc; an AI audio pipeline can check whether an ai_afe simultaneously declares AEC, NS, AGC, and VAD capabilities.

Common query steps:

  1. Call esp_gmf_element_get_caps() to get the capability list.

  2. Call esp_gmf_cap_fetch_node() to find a capability by cap_eightcc.

  3. Call esp_gmf_cap_iterate_attr() or esp_gmf_cap_find_attr() to get capability attributes.

  4. Call esp_gmf_cap_attr_check_value() to determine whether a target value is supported.

Attribute types describe different negotiation methods. Discrete attributes are suitable for listing a set of supported values, such as sample rates or pixel format sets; step attributes describe minimum, maximum, and step values, such as scaled width/height ranges; multiple attributes describe values that change by a factor; constant attributes describe fixed capabilities. Upper-layer pipeline builders can use these for dynamic selection, reducing hardcoded element names and parameters.

Runtime Methods

Runtime methods are the mechanism by which an element exposes runtime control actions externally, used for parameter setting or querying outside of open/process/close, such as setting the target sample rate, adjusting volume, switching EQ presets, or modifying target resolution. Each esp_gmf_method_t contains a method name, execution function, and a list of parameter descriptions.

An element lazily loads its method list via ops.load_methods. The framework calls this callback when needed when external code calls esp_gmf_element_get_method() or esp_gmf_element_exe_method().

static esp_gmf_err_t set_volume(void *handle,
                                esp_gmf_args_desc_t *args,
                                uint8_t *buf, int len)
{
    uint8_t volume = *buf;
    /* Update the element's internal volume state */
    return ESP_GMF_ERR_OK;
}

static esp_gmf_err_t load_methods(esp_gmf_element_handle_t handle)
{
    esp_gmf_method_t *methods = NULL;
    esp_gmf_args_desc_t *args = NULL;

    esp_gmf_args_desc_append(&args, "volume",
                             ESP_GMF_ARGS_TYPE_UINT8,
                             sizeof(uint8_t), 0);
    esp_gmf_method_append(&methods, "set_volume", set_volume, args);

    ESP_GMF_ELEMENT_GET(handle)->method = methods;
    return ESP_GMF_ERR_OK;
}

The caller executes by method name:

uint8_t volume = 80;
esp_gmf_element_exe_method(el, "set_volume", &volume, sizeof(volume));

Method names should remain stable; parameter descriptions tell callers the parameter name, type, size, and offset. When multiple elements implement the same runtime method name, upper-layer applications can depend only on the method name rather than the specific element type; for example, software resampling and hardware ASRC can expose the same target sample rate setting method, and when the pipeline replaces the element, the upper-layer call logic remains unchanged.

Custom Element Template

The following provides a minimal audio element skeleton that connects the element lifecycle, port attributes, and acquire-release calls. The element multiplies input PCM by a gain factor and outputs it.

#include "esp_gmf_audio_element.h"
#include "esp_gmf_oal_mem.h"

typedef struct {
    esp_gmf_audio_element_t parent;
    float                   gain;
} gain_el_t;

typedef struct {
    float gain;
    int   data_size;
} gain_cfg_t;

static esp_gmf_job_err_t gain_open(void *self, void *para)
{
    gain_el_t *el = (gain_el_t *)self;
    gain_cfg_t *cfg = (gain_cfg_t *)OBJ_GET_CFG(self);
    el->gain = cfg->gain;
    return ESP_GMF_JOB_ERR_OK;
}

static esp_gmf_job_err_t gain_process(void *self, void *para)
{
    gain_el_t *el = (gain_el_t *)self;
    esp_gmf_port_handle_t in  = ESP_GMF_ELEMENT_GET_IN_PORT(self);
    esp_gmf_port_handle_t out = ESP_GMF_ELEMENT_GET_OUT_PORT(self);
    esp_gmf_payload_t *in_load = NULL;
    esp_gmf_payload_t *out_load = NULL;

    esp_gmf_err_io_t ret = esp_gmf_port_acquire_in(in, &in_load, 1024, ESP_GMF_MAX_DELAY);
    if (ret < 0) {
        return (ret == ESP_GMF_IO_ABORT) ? ESP_GMF_JOB_ERR_ABORT : ESP_GMF_JOB_ERR_FAIL;
    }

    ret = esp_gmf_port_acquire_out(out, &out_load, in_load->valid_size, ESP_GMF_MAX_DELAY);
    if (ret < 0) {
        esp_gmf_port_release_in(in, in_load, 0);
        return (ret == ESP_GMF_IO_ABORT) ? ESP_GMF_JOB_ERR_ABORT : ESP_GMF_JOB_ERR_FAIL;
    }

    int16_t *src = (int16_t *)in_load->buf;
    int16_t *dst = (int16_t *)out_load->buf;
    int samples = in_load->valid_size / sizeof(int16_t);
    for (int i = 0; i < samples; i++) {
        dst[i] = (int16_t)(src[i] * el->gain);
    }
    out_load->valid_size = in_load->valid_size;
    out_load->is_done = in_load->is_done;

    esp_gmf_port_release_out(out, out_load, 0);
    esp_gmf_port_release_in(in, in_load, 0);
    return in_load->is_done ? ESP_GMF_JOB_ERR_DONE : ESP_GMF_JOB_ERR_OK;
}

static esp_gmf_job_err_t gain_close(void *self, void *para)
{
    return ESP_GMF_JOB_ERR_OK;
}

esp_gmf_err_t gain_el_init(gain_cfg_t *cfg, esp_gmf_element_handle_t *out)
{
    gain_el_t *el = esp_gmf_oal_calloc(1, sizeof(gain_el_t));
    if (!el) {
        return ESP_GMF_ERR_MEMORY_LACK;
    }

    esp_gmf_element_cfg_t el_cfg = { 0 };
    ESP_GMF_ELEMENT_IN_PORT_ATTR_SET(el_cfg.in_attr,
        ESP_GMF_EL_PORT_CAP_SINGLE, 16, 16,
        ESP_GMF_PORT_TYPE_BYTE, cfg->data_size);
    ESP_GMF_ELEMENT_OUT_PORT_ATTR_SET(el_cfg.out_attr,
        ESP_GMF_EL_PORT_CAP_SINGLE, 16, 16,
        ESP_GMF_PORT_TYPE_BYTE, cfg->data_size);
    el_cfg.dependency = true;

    esp_gmf_audio_el_init((esp_gmf_audio_element_handle_t)el, &el_cfg);
    esp_gmf_obj_set_tag((esp_gmf_obj_handle_t)el, "gain");
    esp_gmf_obj_set_config((esp_gmf_obj_handle_t)el, cfg, sizeof(gain_cfg_t));

    esp_gmf_element_t *base = ESP_GMF_ELEMENT_GET(el);
    base->ops.open = gain_open;
    base->ops.process = gain_process;
    base->ops.close = gain_close;

    *out = el;
    return ESP_GMF_ERR_OK;
}

Key points of the template:

  • The custom element struct places the derived base class as the first member, enabling casts between the derived class and the element base class.

  • The configuration struct is bound to the object via esp_gmf_obj_set_config and retrieved in the open callback via OBJ_GET_CFG.

  • The three lifecycle callback functions are defined inside the element and assigned to base->ops at construction time.

  • dependency = true declares that this element requires upstream format info before it can start. If the processing logic does not depend on upstream format, keep the default value of false.

  • In process, acquire_in / release_in and acquire_out / release_out must be strictly paired; each error branch must release any already-acquired payloads, otherwise the port will leak.

  • The is_done of the input payload must be propagated or converted according to processing semantics; return DONE on end-of-stream to let the framework remove the corresponding job from the list.

A constructed element can be registered in the pool, which then copies instances by name and builds pipelines. For pipeline construction and control interfaces, see GMF Pipeline and Task Scheduling.

API Reference

Core header files covered in this document:

  • esp_gmf_element.h: Element base class, lifecycle, port attributes, capability description, and runtime method access interfaces

  • esp_gmf_audio_element.h / esp_gmf_video_element.h / esp_gmf_pic_element.h: Three derived element classes

  • esp_gmf_cap.h: Capability description list, attribute descriptions, and attribute matching

  • esp_gmf_method.h / esp_gmf_args_desc.h / esp_gmf_method_helper.h: Runtime method descriptions, parameter descriptions, and helper calls

Header File

Functions

esp_gmf_err_t esp_gmf_element_init(esp_gmf_element_handle_t handle, esp_gmf_element_cfg_t *config)

Initialize the given element with the configuration.

Parameters:

  • handle – [in] GMF element handle to initialize

  • config – [in] Pointer to the configuration structure

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_element_deinit(esp_gmf_element_handle_t handle)

Deinitialize the specific element, freeing associated resources.

Parameters:

handle – [in] GMF element handle to deinitialize

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_element_set_event_func(esp_gmf_element_handle_t handle, esp_gmf_event_cb cb, void *ctx)

Set the event callback function for the specific element.

Parameters:

  • handle – [in] GMF element handle

  • cb – [in] Event callback function

  • ctx – [in] Context for the callback function

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_element_register_in_port(esp_gmf_element_handle_t handle, esp_gmf_port_handle_t io_inst)

Register an input port for the specific element.

Note

The registered port will be destroyed when esp_gmf_element_unregister_out_port is called

Parameters:

  • handle – [in] GMF element handle

  • io_inst – [in] port handle to register

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid arguments

  • ESP_GMF_ERR_NOT_SUPPORT The specified port type is not supported, or the element can’t connect more port

esp_gmf_err_t esp_gmf_element_unregister_in_port(esp_gmf_element_handle_t handle, esp_gmf_port_handle_t io_inst)

Unregister an input port from the specific element If io_inst is NULL, it unregisters all ports of the element.

Parameters:

  • handle – [in] GMF element handle

  • io_inst – [in] Input port handle to unregister

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

  • ESP_GMF_ERR_NOT_FOUND The specified port was not found

esp_gmf_err_t esp_gmf_element_register_out_port(esp_gmf_element_handle_t handle, esp_gmf_port_handle_t io_inst)

Register an output port for the specific element.

Note

The registered port will be destroyed when esp_gmf_element_unregister_out_port is called

Parameters:

  • handle – [in] GMF element handle

  • io_inst – [in] Output port handle to register

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid arguments

  • ESP_GMF_ERR_NOT_SUPPORT The specified port type is not supported, or the element can’t connect more port

esp_gmf_err_t esp_gmf_element_unregister_out_port(esp_gmf_element_handle_t handle, esp_gmf_port_handle_t io_inst)

Unregister an output port from the specific element If io_inst is NULL, it unregisters all ports of the element.

Parameters:

  • handle – [in] GMF element handle

  • io_inst – [in] Output port handle to unregister

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

  • ESP_GMF_ERR_NOT_FOUND The specified port was not found

esp_gmf_err_t esp_gmf_element_link_el(esp_gmf_element_handle_t handle, esp_gmf_element_handle_t new_el)

Link a new element to the given element.

Parameters:

  • handle – [in] Given element handle

  • new_el – [in] New element handle to link

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_element_get_next_el(esp_gmf_element_handle_t handle, esp_gmf_element_handle_t *next_el)

Get the next linked element by the given element.

Parameters:

  • handle – [in] Given element handle

  • next_el – [in] Next element handle

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_element_get_prev_el(esp_gmf_element_handle_t handle, esp_gmf_element_handle_t *prev_el)

Get the previous linked element by the given element.

Parameters:

  • handle – [in] Given element handle

  • prev_el – [in] Previous element handle

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_job_err_t esp_gmf_element_process_open(esp_gmf_element_handle_t handle, void *para)

Process the open phase for the specific element.

Parameters:

  • handle – [in] GMF element handle

  • para – [in] Pointer to the parameters for processing

Returns:

  • ESP_GMF_JOB_ERR_DONE Indicating the job has been completed

  • ESP_GMF_JOB_ERR_CONTINUE Indicating the job should continue

  • ESP_GMF_JOB_ERR_OK Indicating the job has executed successfully

  • ESP_GMF_JOB_ERR_FAIL Indicating the job has failed to execute

esp_gmf_job_err_t esp_gmf_element_process_close(esp_gmf_element_handle_t handle, void *para)

Process the close phase for the specific element.

Parameters:

  • handle – [in] GMF element handle

  • para – [in] Pointer to the parameters for processing

Returns:

  • ESP_GMF_JOB_ERR_DONE Indicating the job has been completed

  • ESP_GMF_JOB_ERR_CONTINUE Indicating the job should continue

  • ESP_GMF_JOB_ERR_OK Indicating the job has executed successfully

  • ESP_GMF_JOB_ERR_FAIL Indicating the job has failed to execute

esp_gmf_job_err_t esp_gmf_element_process_running(esp_gmf_element_handle_t handle, void *para)

Process the running phase for the specific element.

Parameters:

  • handle – [in] GMF element handle

  • para – [in] Pointer to the parameters for processing

Returns:

  • ESP_GMF_JOB_ERR_DONE Indicating the job has been completed

  • ESP_GMF_JOB_ERR_CONTINUE Indicating the job should continue

  • ESP_GMF_JOB_ERR_OK Indicating the job has executed successfully

  • ESP_GMF_JOB_ERR_FAIL Indicating the job has failed to execute

esp_gmf_job_err_t esp_gmf_element_process_reset(esp_gmf_element_handle_t handle, void *para)

Process the reset phase for the specific element.

Parameters:

  • handle – [in] GMF element handle

  • para – [in] Pointer to the parameters for processing

Returns:

  • ESP_GMF_JOB_ERR_DONE Indicating the job has been completed

  • ESP_GMF_JOB_ERR_CONTINUE Indicating the job should continue

  • ESP_GMF_JOB_ERR_OK Indicating the job has executed successfully

  • ESP_GMF_JOB_ERR_FAIL Indicating the job has failed to execute

esp_gmf_err_t esp_gmf_element_set_state(esp_gmf_element_handle_t handle, esp_gmf_event_state_t new_state)

Set the state of the specific element.

Parameters:

  • handle – [in] GMF element handle

  • new_state – [in] New state to set

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

esp_gmf_err_t esp_gmf_element_get_state(esp_gmf_element_handle_t handle, esp_gmf_event_state_t *state)

Get the state of the specific element.

Parameters:

  • handle – [in] GMF element handle

  • state – [out] Pointer to store the current state

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

esp_gmf_err_t esp_gmf_element_reset_state(esp_gmf_element_handle_t handle)

Reset the state of the specific element to its initial state and clean the job_mask

Parameters:

handle – [in] GMF element handle

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

esp_gmf_err_t esp_gmf_element_reset_port(esp_gmf_element_handle_t handle)

Reset the ports of the specific element to their initial state.

Parameters:

handle – [in] GMF element handle

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

esp_gmf_err_t esp_gmf_element_receive_event(esp_gmf_element_handle_t handle, esp_gmf_event_pkt_t *event, void *ctx)

Receive an event packet for the specific element.

Parameters:

  • handle – [in] GMF element handle

  • event – [in] Pointer to the event packet

  • ctx – [in] Context for event processing

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

esp_gmf_err_t esp_gmf_element_set_job_mask(esp_gmf_element_handle_t handle, uint16_t mask)

Set the job mask of the GMF element to the given mask value.

Parameters:

  • handle – [in] GMF element handle

  • mask – [in] Job mask to set

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

esp_gmf_err_t esp_gmf_element_change_job_mask(esp_gmf_element_handle_t handle, uint16_t mask)

Update the job mask for the specific element by performing a bitwise OR operation with the given mask value.

Parameters:

  • handle – [in] GMF element handle

  • mask – [in] Job mask to apply

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

esp_gmf_err_t esp_gmf_element_get_job_mask(esp_gmf_element_handle_t handle, uint16_t *mask)

Get the job mask for the specific element.

Parameters:

  • handle – [in] GMF element handle

  • mask – [out] Pointer to store the job mask

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

esp_gmf_err_t esp_gmf_element_notify_snd_info(esp_gmf_element_handle_t handle, esp_gmf_info_sound_t *info)

Notify the specific element about sound information.

Parameters:

  • handle – [in] GMF element handle

  • info – [in] Pointer to sound information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_FAIL No event callback function

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

  • Others Failed

esp_gmf_err_t esp_gmf_element_notify_vid_info(esp_gmf_element_handle_t handle, esp_gmf_info_video_t *info)

Notify the specific element about video information.

Parameters:

  • handle – [in] GMF element handle

  • info – [in] Pointer to video information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_FAIL No event callback function

  • ESP_GMF_ERR_INVALID_ARG If the handle is invalid

  • Others Failed

esp_gmf_err_t esp_gmf_element_register_method(esp_gmf_element_handle_t handle, const char *name, esp_gmf_method_func func, esp_gmf_args_desc_t *args_desc)

Register a method for a GMF element. 

    This function registers a method identified by `name` with the GMF element specified by `handle`
    The method is associated with the function pointer `func` and will be executed when called

Note

The registered method and associated resources will be destroyed when the element is destroyed via esp_gmf_element_destroy

Parameters:

  • handle – [in] Handle to the GMF element where the method will be registered

  • name – [in] Name of the method to be registered

  • func – [in] Function pointer to the method implementation

  • args_desc – [in] A pointer to the argument description structure for the method

Returns:

  • ESP_GMF_ERR_OK Method registered successfully

  • ESP_GMF_ERR_MEMORY_LACK Insufficient memory to register the method

  • ESP_GMF_ERR_INVALID_ARG Invalid argument, such as a NULL handle or function pointer

esp_gmf_err_t esp_gmf_element_exe_method(esp_gmf_element_handle_t handle, const char *name, uint8_t *buf, int buf_len)

Execute methods of GMF element by argument list.

Parameters:

  • handle – [in] Pointer to the handle of the GMF element

  • name – [in] The name of the method to be executed

  • buf – [in] Pointer to the buffer containing the arguments for the method

  • buf_len – [in] The length of the buffer (buf)

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_NOT_SUPPORT No executable methods found for the given name

  • ESP_GMF_ERR_INVALID_ARG Invalid handle or arguments

esp_gmf_err_t esp_gmf_element_get_method(esp_gmf_element_handle_t handle, const esp_gmf_method_t **methods)

Retrieve the method structure associated with a given ESP-GMF element.

Parameters:

  • handle – [in] Pointer to the ESP-GMF element handle whose method structure is to be retrieved

  • methods – [out] Pointer to a pointer where the address of the method structure will be stored upon successful retrieval

Returns:

  • ESP_GMF_OK Method structure retrieved successfully

  • ESP_GMF_ERR_INVALID_ARG Invalid argument, such as a NULL handle or output pointer

esp_gmf_err_t esp_gmf_element_get_caps(esp_gmf_element_handle_t handle, const esp_gmf_cap_t **caps)

Retrieve the capability structure associated with a given ESP-GMF element On the first call, if the element’s esp_gmf_load_caps_func is valid, it will load the capability structure by calling esp_gmf_load_caps_func. The created capability structure will be destroyed when the element is destroyed via esp_gmf_element_destroy.

Parameters:

  • handle – [in] Pointer to the ESP-GMF element handle

  • caps – [out] Pointer to a pointer where the address of the capability structure will be stored upon successful retrieval

Returns:

  • ESP_GMF_OK Capability structure successfully retrieved

  • ESP_GMF_ERR_INVALID_ARG Invalid argument, such as a NULL handle or output pointer

Structures

struct esp_gmf_element_port_attr_t

Structure defining the attributes of an element’s port.

Public Members

uint8_t cap

An element can connect to one or more capability ports

esp_gmf_port_attr_t port

Port attributes

int data_size

A minimum data size for element acquisition operations, recommended for all elements, even those without specific processing requirements

struct esp_gmf_element_ops_t

Structure defining the operations of an element.

Public Members

esp_gmf_job_func open

Function to open the element

esp_gmf_job_func process

Function to process the element

esp_gmf_job_func close

Function to close the element

esp_gmf_job_func reset

Function to reset the element

esp_gmf_load_caps_func load_caps

Function to load element capability description

esp_gmf_load_method_func load_methods

Function to load element methods

esp_gmf_event_cb event_receiver

Event receiver function

struct esp_gmf_element

Structure representing a GMF element.

Public Members

esp_gmf_obj_t base

Base object

esp_gmf_element_ops_t ops

Operations

uint8_t job_mask

Job mask

esp_gmf_port_t *in

Input port

esp_gmf_element_port_attr_t in_attr

Input port attributes

esp_gmf_port_t *out

Output port

esp_gmf_element_port_attr_t out_attr

Output port attributes

esp_gmf_event_state_t init_state

Initial state

esp_gmf_event_state_t cur_state

Current state

esp_gmf_event_cb event_func

Event function

esp_gmf_method_t *method

It can access the data members and member functions of the objects

esp_gmf_cap_t *caps

Element capabilities

void *ctx

User Context

uint8_t dependency

Indicates if the element depends on other information to open

struct esp_gmf_element_cfg_t

Configuration structure for a GMF element.

Public Members

void *ctx

User context

esp_gmf_event_cb cb

Callback function

esp_gmf_element_port_attr_t in_attr

Input port attributes

esp_gmf_element_port_attr_t out_attr

Output port attributes

bool dependency

Indicates if the element depends on other information to open

Macros

ESP_GMF_ELEMENT_JOB_OPEN
ESP_GMF_ELEMENT_JOB_PROCESS
ESP_GMF_ELEMENT_JOB_CLOSE
ESP_GMF_ELEMENT_PORT_DATA_SIZE_DEFAULT
ESP_GMF_ELEMENT_PORT_ADDR_ALIGNED_DEFAULT
ESP_GMF_MAX_DELAY
ESP_GMF_ELEMENT_GET(x)
ESP_GMF_ELEMENT_GET_IN_PORT(x)
ESP_GMF_ELEMENT_GET_OUT_PORT(x)
ESP_GMF_ELEMENT_GET_DEPENDENCY(x)
ESP_GMF_ELEMENT_IN_PORT_ATTR_SET(attr, caps, addr_aligned, size_aligned, port_type, acq_data_size)
ESP_GMF_ELEMENT_OUT_PORT_ATTR_SET(attr, caps, addr_aligned, size_aligned, port_type, acq_data_size)
ESP_GMF_EL_PORT_CAP_SINGLE

Defining the bit mask for an element’s port capabilities.

Bit0 for single port capability

ESP_GMF_EL_PORT_CAP_MULTI

Bit1 for multi-port capability

Type Definitions

typedef void *esp_gmf_element_handle_t

The GMF element handle.

typedef esp_gmf_err_t (*esp_gmf_load_caps_func)(esp_gmf_element_handle_t handle)

Function pointer type for load element capability.

typedef esp_gmf_err_t (*esp_gmf_load_method_func)(esp_gmf_element_handle_t handle)

Function pointer type for load element method.

typedef struct esp_gmf_element esp_gmf_element_t

Structure representing a GMF element.

Header File

Functions

esp_gmf_err_t esp_gmf_audio_el_init(esp_gmf_audio_element_handle_t handle, esp_gmf_element_cfg_t *config)

Initialize a GMF audio element with the given configuration.

Parameters:

  • handle – [in] GMF audio element handle to initialize

  • config – [in] Pointer to the configuration structure

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

  • ESP_GMF_ERR_MEMORY_LACK Memory allocate failed

esp_gmf_err_t esp_gmf_audio_el_get_snd_info(esp_gmf_audio_element_handle_t handle, esp_gmf_info_sound_t *info)

Get sound information from a GMF audio element.

Parameters:

  • handle – [in] GMF audio element handle

  • info – [out] Pointer to store the sound information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_audio_el_set_snd_info(esp_gmf_audio_element_handle_t handle, esp_gmf_info_sound_t *info)

Set sound information for a GMF audio element.

Parameters:

  • handle – [in] GMF audio element handle

  • info – [in] Pointer to the sound information to set

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_audio_el_get_file_info(esp_gmf_audio_element_handle_t handle, esp_gmf_info_file_t *info)

Get file information from a GMF audio element.

Parameters:

  • handle – [in] GMF audio element handle

  • info – [out] Pointer to store the file information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_audio_el_set_file_info(esp_gmf_audio_element_handle_t handle, esp_gmf_info_file_t *info)

Set file information for a GMF audio element.

Parameters:

  • handle – [in] GMF audio element handle

  • info – [in] Pointer to the file information to set

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_audio_el_set_file_size(esp_gmf_audio_element_handle_t handle, uint64_t size)

Set the file size for a GMF audio element.

Parameters:

  • handle – [in] GMF audio element handle

  • size – [in] New file size to update

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_audio_el_update_file_pos(esp_gmf_audio_element_handle_t handle, uint64_t pos)

Update the file position for a GMF audio element.

Parameters:

  • handle – [in] GMF audio element handle

  • pos – [in] New file position to update

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_audio_el_deinit(esp_gmf_audio_element_handle_t handle)

Deinitialize a GMF audio element, freeing associated resources.

Parameters:

handle – [in] GMF audio element handle to deinitialize

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

Structures

struct _esp_gmf_audio_element

GMF audio element structure.

Public Members

struct esp_gmf_element base

Base element structure

esp_gmf_info_sound_t snd_info

Sound information

esp_gmf_info_file_t file_info

File information

void *lock

Lock for thread safety

Type Definitions

typedef struct _esp_gmf_audio_element esp_gmf_audio_element_t

GMF audio element structure.

typedef void *esp_gmf_audio_element_handle_t

GMF audio element handle

Header File

Functions

esp_gmf_err_t esp_gmf_video_el_init(esp_gmf_video_element_handle_t handle, esp_gmf_element_cfg_t *config)

Initialize a GMF video element with the given configuration.

Parameters:

  • handle – [in] GMF video element handle to initialize

  • config – [in] Pointer to the configuration structure

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

  • ESP_GMF_ERR_MEMORY_LACK Memory allocate failed

esp_gmf_err_t esp_gmf_video_el_get_src_info(esp_gmf_video_element_handle_t handle, esp_gmf_info_video_t *info)

Get video source information from a GMF video element.

Parameters:

  • handle – [in] GMF video element handle

  • info – [out] Pointer to store the video source information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_video_el_set_src_info(esp_gmf_video_element_handle_t handle, esp_gmf_info_video_t *info)

Set video source information from a GMF video element.

Parameters:

  • handle – [in] GMF video element handle

  • info – [out] Pointer to the video source information to set

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_video_el_deinit(esp_gmf_video_element_handle_t handle)

Deinitialize a GMF video element, freeing associated resources.

Parameters:

handle – [in] GMF video element handle to deinitialize

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

Structures

struct _esp_gmf_video_element

GMF video element structure.

Public Members

struct esp_gmf_element base

Base element structure

esp_gmf_info_video_t src_info

Video input information

void *lock

Lock for thread safety

Type Definitions

typedef struct _esp_gmf_video_element esp_gmf_video_element_t

GMF video element structure.

typedef void *esp_gmf_video_element_handle_t

GMF video element handle

Header File

Functions

esp_gmf_err_t esp_gmf_pic_el_init(esp_gmf_pic_element_handle_t handle, esp_gmf_element_cfg_t *config)

Initialize a GMF picture element with the given configuration.

Parameters:

  • handle – [in] GMF picture element handle to initialize

  • config – [in] Pointer to the configuration structure

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

  • ESP_GMF_ERR_MEMORY_LACK Memory allocate failed

esp_gmf_err_t esp_gmf_pic_el_get_metadata(esp_gmf_pic_element_handle_t handle, esp_gmf_info_metadata_t *meta)

Get metadata from a GMF picture element.

Parameters:

  • handle – [in] GMF picture element handle

  • meta – [out] Pointer to store the metadata information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pic_el_set_metadata(esp_gmf_pic_element_handle_t handle, void *value, int len)

Set metadata for a GMF picture element.

Parameters:

  • handle – [in] GMF picture element handle

  • value – [in] Pointer to the metadata value

  • len – [in] Length of the metadata value

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

  • ESP_GMF_ERR_MEMORY_LACK Memory allocate failed

esp_gmf_err_t esp_gmf_pic_el_get_file_info(esp_gmf_pic_element_handle_t handle, esp_gmf_info_file_t *info)

Get file information from a GMF picture element.

Parameters:

  • handle – [in] GMF picture element handle

  • info – [out] Pointer to store the file information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pic_el_set_file_info(esp_gmf_pic_element_handle_t handle, esp_gmf_info_file_t *info)

Set file information for a GMF picture element.

Parameters:

  • handle – [in] GMF picture element handle

  • info – [in] Pointer to the file information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pic_el_get_pic_info(esp_gmf_pic_element_handle_t handle, esp_gmf_info_pic_t *info)

Get picture information from a GMF picture element.

Parameters:

  • handle – [in] GMF picture element handle

  • info – [out] Pointer to store the picture information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pic_el_set_pic_info(esp_gmf_pic_element_handle_t handle, esp_gmf_info_pic_t *info)

Set picture information for a GMF picture element.

Parameters:

  • handle – [in] GMF picture element handle

  • info – [in] Pointer to the picture information

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pic_el_set_file_size(esp_gmf_pic_element_handle_t handle, uint64_t size)

Set the file size for a GMF picture element.

Parameters:

  • handle – [in] GMF picture element handle

  • size – [in] New file size to update

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pic_el_update_file_pos(esp_gmf_pic_element_handle_t handle, uint64_t pos)

Update the file position for a GMF picture element.

Parameters:

  • handle – [in] GMF picture element handle

  • pos – [in] New file position to update

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pic_el_deinit(esp_gmf_pic_element_handle_t handle)

Deinitialize a GMF picture element, freeing associated resources.

Parameters:

handle – [in] GMF picture element handle to deinitialize

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument

Structures

struct _esp_gmf_pic_element

GMF picture element structure.

Public Members

struct esp_gmf_element base

Base element structure

esp_gmf_info_metadata_t meta_info

Picture metadata information

esp_gmf_info_pic_t pic_info

Picture information

esp_gmf_info_file_t file_info

File information

void *lock

Lock for thread safety

Type Definitions

typedef struct _esp_gmf_pic_element esp_gmf_pic_element_t

GMF picture element structure.

typedef void *esp_gmf_pic_element_handle_t

GMF picture element handle

Header File

Functions

esp_gmf_err_t esp_gmf_cap_append(esp_gmf_cap_t **caps, esp_gmf_cap_t *cap_value)

Create a new capability node based on the given cap_value and append it to the capability linked list.

Parameters:

  • caps – [inout] Pointer to the head of the capability linked list. If *caps is NULL, a new list will be created

  • cap_value – [in] Pointer to the capability data to be appended

Returns:

  • ESP_GMF_ERR_OK Successfully appended the capability

  • ESP_GMF_ERR_MEMORY_LACK Insufficient memory to create a new capability node

  • ESP_GMF_ERR_INVALID_ARG Invalid argument (e.g., NULL pointer)

esp_gmf_err_t esp_gmf_cap_destroy(esp_gmf_cap_t *caps)

Destroy a linked list of capabilities.

Parameters:

caps – [in] Pointer to the head of the capability linked list

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG The argument is invalid

esp_gmf_err_t esp_gmf_cap_fetch_node(esp_gmf_cap_t *caps, uint64_t eight_cc, esp_gmf_cap_t **out_caps)

Fetch a capability node from a capability list using an 8-character code.

Parameters:

  • caps – [in] Pointer to the head of the capability list to search

  • eight_cc – [in] 8-character code representing the capability to find (as uint64_t)

  • out_caps – [out] Pointer to the variable that will receive the found capability node

Returns:

  • ESP_GMF_ERR_OK The capability was found successfully

  • ESP_GMF_ERR_INVALID_ARG One or more arguments are invalid (e.g., NULL pointers)

  • ESP_GMF_ERR_NOT_FOUND No matching capability was found; *out_caps will be set to NULL

esp_gmf_err_t esp_gmf_cap_iterate_attr(esp_gmf_cap_t *caps, uint32_t attr_index, esp_gmf_cap_attr_t *out_attr)

Iterate over capability attributes by index.

Parameters:

  • caps – [in] Pointer to the capability being iterated

  • attr_index – [in] Index of the attribute to retrieve

  • out_attr – [out] Pointer to store the retrieved attribute

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG The argument isinvalid

  • ESP_GMF_ERR_NOT_SUPPORT The cap_attr_iter_fun is invalid

  • ESP_GMF_ERR_NOT_FOUND The attr_index is out of range

esp_gmf_err_t esp_gmf_cap_find_attr(esp_gmf_cap_t *caps, uint32_t cc, esp_gmf_cap_attr_t *out_attr)

Find an attribute from a given capability using a 4-character code.

Parameters:

  • caps – [in] Pointer to the capability to search

  • cc – [in] Character code of the attribute to find

  • out_attr – [out] Pointer to store the found attribute

Returns:

  • ESP_GMF_ERR_OK The attribute is found

  • ESP_GMF_ERR_INVALID_ARG The argument is invalid

  • ESP_GMF_ERR_NOT_FOUND The attribute is not found

esp_gmf_err_t esp_gmf_cap_attr_check_value(esp_gmf_cap_attr_t *attr, uint32_t val, bool *is_support)

Check if a given value is supported by an attribute.

Parameters:

  • attr – [in] Pointer to the attribute to check

  • val – [in] Value to check

  • is_support – [out] Pointer to boolean indicating if the value is supported

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG The argument is invalid

  • ESP_GMF_ERR_NOT_SUPPORT If the value or attribute type is not support

esp_gmf_err_t esp_gmf_cap_attr_iterator_value(esp_gmf_cap_attr_t *attr, uint32_t *val, bool *is_last)

Iterate through values of an attribute.

Parameters:

  • attr – [inout] Pointer to the attribute iterator

  • val – [out] Pointer to store the current value

  • is_last – [out] Pointer to boolean indicating if this is the last value

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_INVALID_ARG The argument is invalid

  • ESP_GMF_ERR_NOT_SUPPORT If the value or attribute type is not support

esp_gmf_err_t esp_gmf_cap_attr_get_first_value(esp_gmf_cap_attr_t *attr, uint32_t *val)

Retrieve the first valid value of an attribute.

Parameters:

  • iter – [inout] Pointer to the attribute

  • val – [out] Pointer to store the retrieved value

Returns:

  • ESP_GMF_ERR_OK Success

  • ESP_GMF_ERR_INVALID_ARG Invalid argument (e.g., iter or val is NULL)

  • ESP_GMF_ERR_NOT_SUPPORT The attribute type does not support this operation

Structures

struct esp_gmf_prop_discrete_t

Structure for discrete properties in capabilities.

Public Members

void *collection

Pointer to the collection of discrete values

uint16_t item_num

Number of items in the collection

uint16_t item_size

Size of each item in bytes (1, 2, or 4)

struct esp_gmf_prop_stepwise_t

Structure for stepwise properties in capabilities, e.g. An = min + (n-1) * step.

Public Members

uint32_t min

Minimum value of the property

uint32_t step

Step size between values

uint32_t max

Maximum value of the property

struct esp_gmf_prop_multiple_t

Structure for multiple properties in capabilities, e.g. M = factor * n, n:1~N.

Public Members

uint32_t min

Minimum value of the property

uint16_t factor

Multiplicative factor between values

uint32_t max

Maximum value of the property

struct esp_gmf_prop_constant_t

Structure for constant properties in capabilities.

Public Members

uint32_t data

The constant value of the property

struct esp_gmf_cap_attr

Structure for attributes of a capability.

Public Members

uint32_t fourcc

Unique 4-character code identifying the attribute

uint8_t index

Index of the discrete attribute only

uint8_t prop_type

Type of property (discrete, stepwise, or multiple)

esp_gmf_prop_discrete_t d

Discrete property data

esp_gmf_prop_stepwise_t s

Stepwise property data

esp_gmf_prop_multiple_t m

Multiple property data

esp_gmf_prop_constant_t c

Constant property data

union esp_gmf_cap_attr::[anonymous] value

Union holding the property value based on prop_type

struct esp_gmf_cap_perf_t

Structure for performance metrics of a capability.

Public Members

uint32_t oper_per_sec

Number of operations per second (or a percentage)

struct esp_gmf_cap

Structure representing a capability with performance metrics and attributes.

Public Members

struct esp_gmf_cap *next

Pointer to the next capability in a linked list

uint64_t cap_eightcc

Unique 8-character code for identifying the capability

esp_gmf_cap_perf_t perf

Performance metrics associated with the capability

cap_attr_iter_fun attr_fun

Function pointer for iterating over attributes in the capability

void *attr_fun_ctx

Function pointer for iterating over attributes in the capability

Macros

ESP_GMF_CAP_ATTR_SET_DISCRETE(attr, code, coll, num, size)

Macro to set discrete attribute parameters in esp_gmf_cap_attr_t.

ESP_GMF_CAP_ATTR_SET_STEPWISE(attr, code, min_val, step_size, max_val)

Macro to set stepwise attribute parameters in esp_gmf_cap_attr_t.

ESP_GMF_CAP_ATTR_SET_MULTIPLE(attr, code, min_val, factor_val, max_val)

Macro to set multiple attribute parameters in esp_gmf_cap_attr_t.

ESP_GMF_CAP_ATTR_SET_CONSTANT(attr, code, factor_val)

Macro to set constant attribute parameters in esp_gmf_cap_attr_t.

Type Definitions

typedef struct esp_gmf_cap_attr esp_gmf_cap_attr_t

Structure for attributes of a capability.

typedef esp_gmf_err_t (*cap_attr_iter_fun)(uint32_t index, esp_gmf_cap_attr_t *attr)

Function pointer type for iterating over capability attributes.

typedef struct esp_gmf_cap esp_gmf_cap_t

Structure representing a capability with performance metrics and attributes.

Enumerations

enum esp_gmf_prop_type

Enumeration for property types in capabilities.

Values:

enumerator ESP_GMF_PROP_TYPE_NONE

No property type specified

enumerator ESP_GMF_PROP_TYPE_DISCRETE

Discrete property with distinct values

enumerator ESP_GMF_PROP_TYPE_STEPWISE

Stepwise property with specified min, max, and step

enumerator ESP_GMF_PROP_TYPE_MULTIPLE

Multiple property with min, max, and multiplicative factor

enumerator ESP_GMF_PROP_TYPE_CONSTANT

Constant property with a single value

Header File

Functions

static inline esp_gmf_err_t esp_gmf_method_create(const char *name, esp_gmf_method_func func, esp_gmf_args_desc_t *args, esp_gmf_method_t **handle)

Create a new GMF method This function creates a new GMF method and initializes its members.

Note

The name argument must have global or static scope to ensure validity throughout the method’s operation

Parameters:

  • name – [in] Name of the method

  • func – [in] Function pointer to the method implementation

  • args – [in] The arguments description list

  • handle – [out] Pointer to the handle for the newly created method

Returns:

  • ESP_GMF_ERR_OK Success

  • ESP_GMF_ERR_MEMORY_LACK Memory allocation failure

static inline esp_gmf_err_t esp_gmf_method_append(esp_gmf_method_t **head, const char *name, esp_gmf_method_func func, esp_gmf_args_desc_t *args)

Append a new GMF method to the method list This function creates a new GMF method and appends it to the provided method list.

Note

The name argument must have global or static scope to ensure validity throughout the method’s operation

Parameters:

  • head – [inout] Pointer to the head of the method list

  • name – [in] Name of the method

  • func – [in] Function pointer to the method implementation

  • args – [in] The arguments description list

Returns:

  • ESP_GMF_ERR_OK Success

  • ESP_GMF_ERR_MEMORY_LACK Memory allocation failure

static inline void esp_gmf_method_destroy(esp_gmf_method_t *head)

Destroy a GMF method list.

Parameters:

head – [in] Pointer to the head of the method list

static inline void esp_gmf_method_show(esp_gmf_method_t *head)

Display the list of GMF methods and their argument descriptions.

Parameters:

head – [in] Pointer to the head of the method list

static inline esp_gmf_err_t esp_gmf_method_found(const esp_gmf_method_t *head, const char *wanted_name, const esp_gmf_method_t **wanted_method)

Find a method by name in a linked list of methods.

Parameters:

  • head – [in] Pointer to the head of the linked list of methods

  • wanted_name – [in] The name of the method to search for

  • wanted_method – [out] Pointer to store the found method, if any. Set to NULL if not found.

Returns:

  • ESP_GMF_ERR_OK The method was found successfully

  • ESP_GMF_ERR_NOT_FOUND The method with the specified name was not found

static inline esp_gmf_err_t esp_gmf_method_query_args(esp_gmf_method_t *head, esp_gmf_args_desc_t **args)

Query the argument descriptors of a method.

Parameters:

  • head – [in] Pointer to the method structure from which arguments will be queried

  • args – [out] Pointer to store the retrieved argument descriptors Set to NULL if the method has no arguments

Returns:

  • ESP_GMF_ERR_OK The argument descriptors were successfully retrieved

  • ESP_GMF_ERR_INVALID_ARG The head or args pointer is invalid (e.g., NULL)

Structures

struct esp_gmf_method

Structure for GMF methods This structure defines a linked list node for storing GMF methods.

Public Members

struct esp_gmf_method *next

Pointer to the next method node

const char *name

Name of the method

esp_gmf_method_func func

Function pointer to the method implementation

uint16_t args_cnt

Number of the argument description

esp_gmf_args_desc_t *args_desc

A pointer to argument description structure

Type Definitions

typedef esp_gmf_err_t (*esp_gmf_method_func)(void *handle, esp_gmf_args_desc_t *arg_desc, uint8_t *buf, int buf_len)

Function pointer type for GMF method functions This typedef defines the function pointer type for GMF method functions.

typedef struct esp_gmf_method esp_gmf_method_t

Structure for GMF methods This structure defines a linked list node for storing GMF methods.

Header File

Functions

static inline esp_gmf_err_t esp_gmf_args_desc_create(const char *name, esp_gmf_args_type_t type, esp_gmf_args_desc_t *val, uint32_t size, esp_gmf_args_desc_t **handle)

Create a new argument description node.

Note

The name is not copied, so it must have global or static scope to remain valid throughout the method’s operation

Parameters:

  • name – [in] Name of the argument

  • type – [in] Type of the argument

  • val – [in] Nested value for arrays or sublists

  • size – [in] Size of the argument

  • handle – [out] Pointer to the created node

Returns:

  • ESP_GMF_ERR_OK Success

  • ESP_GMF_ERR_MEMORY_LACK Memory allocation failure

static inline void esp_gmf_args_desc_destroy(esp_gmf_args_desc_t *head)

Destroy a esp_gmf_args_desc node and all its successors.

Parameters:

head – [in] Pointer to the head of the list to be destroyed

static inline esp_gmf_err_t esp_gmf_args_desc_get_total_size(esp_gmf_args_desc_t *head, size_t *total_value_size)

Calculate the total size of all argument values in a linked list of GMF argument descriptions.

Parameters:

  • head – [in] Pointer to the head of the linked list of argument descriptions

  • total_value_size – [out] Pointer to the variable where the total size will be stored

Returns:

  • ESP_GMF_ERR_OK Success, the total size is stored in total_value_size

  • ESP_GMF_ERR_INVALID_ARG If either the head or total_value_size pointer is NULL

static inline esp_gmf_err_t esp_gmf_args_desc_append_base(esp_gmf_args_desc_t **head, const char *name, esp_gmf_args_type_t type, uint32_t size, uint32_t offset, esp_gmf_args_desc_t *val)

Append a new argument description to the linked list of argument descriptions. This function creates a new argument description node and appends it to the end of the linked list. The new node is initialized with the specified name, type, size, offset, and a pointer to a val structure that contains additional argument-specific data.

Note

The name is not copied, so it must have global or static scope to remain valid throughout the method’s operation

Parameters:

  • head – [inout] Pointer to the head of the linked list. This is a pointer to the first node in the list, and it will be updated if the new node is added at the head

  • name – [in] The name of the argument, which will be stored in the new node

  • type – [in] The type of the argument (e.g., integer, array, etc.)

  • size – [in] The size of the argument value

  • offset – [in] The offset of the argument in the structure or buffer

  • val – [in] Pointer to a structure containing additional data related to the argument

Returns:

  • ESP_GMF_ERR_OK Success, the new argument description is appended to the list

  • ESP_GMF_ERR_INVALID_ARG If head or name is NULL

static inline esp_gmf_err_t esp_gmf_args_desc_append(esp_gmf_args_desc_t **head, const char *name, esp_gmf_args_type_t type, uint32_t size, uint32_t offset)

Append a new argument description for a non-array argument to the linked list.

Note

The name is not copied, so it must have global or static scope to remain valid throughout the method’s operation

Parameters:

  • head – [inout] Pointer to the head of the linked list. This is a pointer to the first node in the list, and it will be updated if the new node is added at the head

  • name – [in] The name of the argument, which will be stored in the new node

  • type – [in] The type of the argument (e.g., integer, array, etc.)

  • size – [in] The size of the argument value

  • offset – [in] The offset of the argument in the structure or buffer

Returns:

  • ESP_GMF_ERR_OK Success, the new argument description is appended to the list

  • ESP_GMF_ERR_INVALID_ARG If head or name is NULL

static inline esp_gmf_err_t esp_gmf_args_desc_append_array(esp_gmf_args_desc_t **head, const char *name, esp_gmf_args_desc_t *val, uint32_t size, uint32_t offset)

Append a new argument description for an array argument to the linked list. 

    This function wraps the `esp_gmf_args_desc_append_base` function to append a new argument description
    for an array argument (where `val` is a pointer to the array's value structure) to the linked list
    It sets the argument type to `ESP_GMF_ARGS_TYPE_ARRAY` and uses the provided `name`, `size`, and `offset`
    to create the new argument description
Parameters:

  • head – [inout] Pointer to the head of the linked list. This is a pointer to the first node in the list, and it will be updated if the new node is added at the head

  • name – [in] The name of the argument, which will be stored in the new node

  • val – [in] Pointer to a structure containing the array data associated with the argument

  • size – [in] The size of the array (e.g., the total number of elements)

  • offset – [in] The offset of the argument in the structure or buffer

Returns:

  • ESP_GMF_ERR_OK Success, the new argument description is appended to the list

  • ESP_GMF_ERR_INVALID_ARG If head or name is NULL

static inline esp_gmf_err_t esp_gmf_args_desc_copy(const esp_gmf_args_desc_t *head, esp_gmf_args_desc_t **new_args)

Copy an entire GMF argument description list.

Parameters:

  • head – [in] Pointer to the head of the list to be copied

  • new_args – [out] Pointer to the head of the newly copied list

Returns:

  • ESP_GMF_ERR_OK Success

  • ESP_GMF_ERR_MEMORY_LACK Memory allocation failure

  • ESP_GMF_ERR_INVALID_ARG Invalid input arguments

static inline size_t esp_gmf_args_desc_count(esp_gmf_args_desc_t *head)

Count the number of nodes in a GMF argument description list, including nested lists.

Parameters:

head – [in] Pointer to the head of the list

Returns:

  • The total number of nodes in the list, including nested lists

static inline esp_gmf_err_t esp_gmf_args_desc_found(esp_gmf_args_desc_t *head, const char *wanted_name, esp_gmf_args_desc_t **wanted_arg)

Find an argument description by its name in the linked list.

Parameters:

  • head – [in] Pointer to the head of the linked list

  • wanted_name – [in] The name of the argument that is being searched for

  • wanted_arg – [out] A pointer to a pointer where the found argument description will be stored If the argument is found, wanted_arg will point to the corresponding node

Returns:

  • ESP_GMF_ERR_OK Success, the argument description was found, and wanted_arg is updated

  • ESP_GMF_ERR_NOT_FOUND If no argument with the specified wanted_name is found

  • ESP_GMF_ERR_INVALID_ARG If head, wanted_name, or wanted_arg is NULL

static inline esp_gmf_err_t esp_gmf_args_extract_value(esp_gmf_args_desc_t *head, const char *name, uint8_t *buf, uint32_t buf_len, uint32_t *value)

Extracts a specific type value from the raw data buffer.

Parameters:

  • head – [in] Pointer to the argument descriptor list

  • name – [in] The name of the argument whose value needs to be extracted

  • buf – [in] The buffer containing raw data from which the value will be extracted

  • buf_len – [in] The size of the buffer buf

  • value – [out] Pointer to store the extracted value

Returns:

  • ESP_OK If the value was successfully extracted from the buffer

  • ESP_ERR_NOT_FOUND If the specified argument name was not found

static inline esp_gmf_err_t esp_gmf_args_set_value(esp_gmf_args_desc_t *head, const char *name, uint8_t *buf, uint8_t *value, uint32_t value_len)

Sets a specific value into the raw data buffer.

Parameters:

  • head – [in] Pointer to the argument descriptor list

  • name – [in] The name of the argument where the value needs to be set

  • buf – [in] The buffer where the value will be set, it stores raw data

  • value – [in] The value that will be written into the buf

  • value_len – [in] The size of the value in bytes

Returns:

  • ESP_OK If the value was successfully extracted from the buffer

  • ESP_ERR_NOT_FOUND If the specified argument name was not found

static inline esp_gmf_err_t esp_gmf_args_extract_uint8(esp_gmf_args_desc_t *head, const char *name, uint8_t *buf, uint8_t *buf_len, uint8_t *value)

Extract a uint8_t value from the GMF argument description list.

Parameters:

  • head – [in] Pointer to the head of the argument list

  • name – [in] The name of the argument to extract

  • buf – [in] Pointer to the buffer containing argument values

  • buf_len – [in] Length of the buffer (not used in this function)

  • value – [out] Pointer to store the extracted uint64_t value

Returns:

  • ESP_GMF_ERR_OK Value extracted successfully

  • ESP_GMF_ERR_NOT_FOUND Argument not found in the list

static inline esp_gmf_err_t esp_gmf_args_extract_uint16(esp_gmf_args_desc_t *head, const char *name, uint8_t *buf, uint8_t *buf_len, uint16_t *value)

Extract a uint16_t value from the GMF argument description list.

Parameters:

  • head – [in] Pointer to the head of the argument list

  • name – [in] The name of the argument to extract

  • buf – [in] Pointer to the buffer containing argument values

  • buf_len – [in] Length of the buffer (not used in this function)

  • value – [out] Pointer to store the extracted uint64_t value

Returns:

  • ESP_GMF_ERR_OK Value extracted successfully

  • ESP_GMF_ERR_NOT_FOUND Argument not found in the list

static inline esp_gmf_err_t esp_gmf_args_extract_uint32(esp_gmf_args_desc_t *head, const char *name, uint8_t *buf, uint8_t *buf_len, uint32_t *value)

Extract a uint32_t value from the GMF argument description list.

Parameters:

  • head – [in] Pointer to the head of the argument list

  • name – [in] The name of the argument to extract

  • buf – [in] Pointer to the buffer containing argument values

  • buf_len – [in] Length of the buffer (not used in this function)

  • value – [out] Pointer to store the extracted uint64_t value

Returns:

  • ESP_GMF_ERR_OK Value extracted successfully

  • ESP_GMF_ERR_NOT_FOUND Argument not found in the list

static inline esp_gmf_err_t esp_gmf_args_extract_uint64(esp_gmf_args_desc_t *head, const char *name, uint8_t *buf, uint8_t *buf_len, uint64_t *value)

Extract a uint64_t value from the GMF argument description list.

Parameters:

  • head – [in] Pointer to the head of the argument list

  • name – [in] The name of the argument to extract

  • buf – [in] Pointer to the buffer containing argument values

  • buf_len – [in] Length of the buffer (not used in this function)

  • value – [out] Pointer to store the extracted uint64_t value

Returns:

  • ESP_GMF_ERR_OK Value extracted successfully

  • ESP_GMF_ERR_NOT_FOUND Argument not found in the list

static inline esp_gmf_err_t esp_gmf_args_extract_float(esp_gmf_args_desc_t *head, const char *name, uint8_t *buf, uint8_t *buf_len, uint64_t *value)

Extract a float value from the GMF argument description list.

Parameters:

  • head – [in] Pointer to the head of the argument list

  • name – [in] The name of the argument to extract

  • buf – [in] Pointer to the buffer containing argument values

  • buf_len – [in] Length of the buffer (not used in this function)

  • value – [out] Pointer to store the extracted float value

Returns:

  • ESP_GMF_ERR_OK Value extracted successfully

  • ESP_GMF_ERR_NOT_FOUND Argument not found in the list

static inline esp_gmf_err_t esp_gmf_args_extract_double(esp_gmf_args_desc_t *head, const char *name, uint8_t *buf, uint8_t *buf_len, uint64_t *value)

Extract a double value from the GMF argument description list.

Parameters:

  • head – [in] Pointer to the head of the argument list

  • name – [in] The name of the argument to extract

  • buf – [in] Pointer to the buffer containing argument values

  • buf_len – [in] Length of the buffer (not used in this function)

  • value – [out] Pointer to store the extracted double value

Returns:

  • ESP_GMF_ERR_OK Value extracted successfully

  • ESP_GMF_ERR_NOT_FOUND Argument not found in the list

static inline void esp_gmf_args_desc_show(esp_gmf_args_desc_t *head, const char *func, size_t line)

Display the argument descriptions in the linked list The function uses indentation (”–”) to visually represent the depth of any nested structures or arrays.

Parameters:

  • head – [in] Pointer to the head of the linked list containing argument descriptions

  • func – [in] The name of the function from which this logging function is called

  • line – [in] The line number in the source code from which this function is called

Structures

struct esp_gmf_args_desc

GMF argument description structure.

Public Members

struct esp_gmf_args_desc *next

Pointer to the next argument in the list

esp_gmf_args_type_t type

Data type of the argument

uint16_t offset

Byte offset from the previous argument

const char *name

Name of the argument

struct esp_gmf_args_desc *val

Pointer to nested value (used for arrays)

uint32_t size

Size of the argument in bytes

Macros

ESP_GMF_ARGS_DESC_PRINT(x)

A macro to print the argument descriptor details.

Type Definitions

typedef struct esp_gmf_args_desc esp_gmf_args_desc_t

GMF argument description structure.

Enumerations

enum esp_gmf_args_type_t

GMF argument types enumeration.

Values:

enumerator ESP_GMF_ARGS_TYPE_NIL

No type or null value

enumerator ESP_GMF_ARGS_TYPE_UINT8

Unsigned 8-bit integer

enumerator ESP_GMF_ARGS_TYPE_INT8

Signed 8-bit integer

enumerator ESP_GMF_ARGS_TYPE_UINT16

Unsigned 16-bit integer

enumerator ESP_GMF_ARGS_TYPE_INT16

Signed 16-bit integer

enumerator ESP_GMF_ARGS_TYPE_UINT32

Unsigned 32-bit integer

enumerator ESP_GMF_ARGS_TYPE_INT32

Signed 32-bit integer

enumerator ESP_GMF_ARGS_TYPE_UINT64

Unsigned 64-bit integer

enumerator ESP_GMF_ARGS_TYPE_INT64

Signed 64-bit integer

enumerator ESP_GMF_ARGS_TYPE_FLOAT

Single-precision floating point

enumerator ESP_GMF_ARGS_TYPE_DOUBLE

Double-precision floating point

enumerator ESP_GMF_ARGS_TYPE_ARRAY

Array data type

Header File

Functions

static inline esp_gmf_err_t esp_gmf_method_prepare_exec_ctx(const esp_gmf_method_t *method_head, const char *method_name, esp_gmf_method_exec_ctx_t *exec_ctx)

Prepare for method execution context by method name.

Parameters:

  • method_head – [in] Header of GMF methods

  • method_name – [in] Method name to be searched

  • exec_ctx – [out] Pointer to method execution context

Returns:

  • ESP_GMF_ERR_OK On success

  • ESP_GMF_ERR_NOT_FOUND Not found method for the method name

  • ESP_GMF_ERR_MEMORY_LACK Not enough memory for method execution buffer

static inline void esp_gmf_method_release_exec_ctx(esp_gmf_method_exec_ctx_t *exec_ctx)

Release for method execution context.

Parameters:

exec_ctx – [in] Pointer to method execution context

Structures

struct esp_gmf_method_exec_ctx

Structure for GMF method execution context This structure holds the necessary information to execute a GMF method Including the method pointer and buffer to store execution settings.

Public Members

const esp_gmf_method_t *method

Pointer to the matched method to be executed

uint8_t *exec_buf

Buffer to store executed settings

size_t buf_size

Executed buffer size

Macros

ESP_GMF_METHOD_DEF(category, module, method, str)

Define a GMF method identifier. 

    This macro defines a string identifier for a GMF method,
    making the code more readable and understandable. The identifier is composed of
    three parts:
      1. Category: The method's category (e.g., VIDEO)
      2. Module: The module to which the method belongs (e.g., ENCODER)
      3. Method: The method name itself (e.g., SET_DST_CODEC)

    Example usage:
      ESP_GMF_METHOD_DEF(VIDEO, ENCODER, SET_DST_CODEC, "set_dst_codec")
ESP_GMF_METHOD_STR(category, module, method)

Retrieve the string representation of a method defined with ESP_GMF_METHOD_DEF.

ESP_GMF_METHOD_ARG_DEF(category, module, method, arg, str)

Define a GMF method argument identifier. 

    This macro defines a string identifier for a method argument, improving code readability.
    The identifier is composed of four parts:
      1. Category: The method's category (e.g., VIDEO)
      2. Module: The module to which the method belongs (e.g., ENCODER)
      3. Method: The method name (e.g., SET_DST_CODEC)
      4. Argument: The argument name (e.g., CODEC)

    Example usage:
      ESP_GMF_METHOD_ARG_DEF(VIDEO, ENCODER, SET_DST_CODEC, CODEC, "codec")
ESP_GMF_METHOD_ARG_STR(category, module, method, arg)

Retrieve the string representation of a method argument defined with ESP_GMF_METHOD_ARG_DEF

Type Definitions

typedef struct esp_gmf_method_exec_ctx esp_gmf_method_exec_ctx_t

Structure for GMF method execution context This structure holds the necessary information to execute a GMF method Including the method pointer and buffer to store execution settings.

Was this page helpful?