# 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

- gmf_core/include/esp_gmf_element.h

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

- gmf_core/include/esp_gmf_audio_element.h

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

- gmf_core/include/esp_gmf_video_element.h

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

- gmf_core/include/esp_gmf_pic_element.h

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

- gmf_core/include/esp_gmf_cap.h

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

- gmf_core/include/esp_gmf_method.h

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

- gmf_core/include/esp_gmf_args_desc.h

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

- gmf_core/include/esp_gmf_method_helper.h

### 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?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.