# GMF 处理单元

[English]

处理单元（element）是 GMF-Core 中承载具体处理逻辑的对象。解码、编码、重采样、混音、图像缩放等步骤都以处理单元形式接入处理链；处理链负责编排连接关系，执行线程负责调度处理单元的功能函数，处理单元只实现自身的初始化、处理与资源回收逻辑。

数据载体（payload）、数据端口（port）与 acquire-release 协议见 数据流转。处理链（pipeline）编排、执行线程（task）调度、状态与错误处理见 GMF 处理链与任务调度。整体对象关系参考 GMF-Core 概览。

## 生命周期与对象结构

处理单元继承自对象基类 `esp_gmf_obj_t`，基类提供 tag、配置数据、复制与销毁接口；处理单元基类 `esp_gmf_element_t` 在此基础上增加生命周期功能函数、输入输出数据端口、能力描述、运行时方法和事件接收接口。

处理单元必须实现三个主要功能函数：

- `open`：一次性初始化资源，例如创建算法句柄、读取配置、根据上游格式信息计算内部参数。

- `process`：执行一次数据处理，通常从输入数据端口获取数据载体，处理后写入输出数据端口。

- `close`：释放 `open` 阶段申请的资源。无论处理链正常结束、停止还是出错，框架都会尝试为已 open 的处理单元执行 close。

处理单元还可以实现 `reset` 与 `event_receiver`。前者用于重置内部状态，后者用于接收上游格式信息、处理链事件或应用侧事件。需要依赖上游格式信息才能 open 的处理单元，应在配置中设置 `dependency = true`，由处理链在收到 REPORT_INFO 事件后再注册它的 open/process job，流程见 GMF 处理链与任务调度 的依赖型处理单元章节。

按媒体类别，GMF-Core 提供三类派生处理单元。

派生类 | 格式信息 | 典型字段
--- | --- | ---
`esp_gmf_audio_element_t` | `esp_gmf_info_sound_t` | 采样率、声道、位深、FourCC
`esp_gmf_video_element_t` | `esp_gmf_info_video_t` | 分辨率、帧率、FourCC
`esp_gmf_pic_element_t` | `esp_gmf_info_pic_t` | 宽、高、FourCC

## 数据端口属性

处理单元在初始化时声明输入输出数据端口的约束，包括端口数量、缓冲区对齐、端口类型和每次 acquire 推荐的数据量。这些约束由 `esp_gmf_element_port_attr_t` 描述，通常通过宏设置。

    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` 表示端口只能连接一个对端，`ESP_GMF_EL_PORT_CAP_MULTI` 表示允许多个对端共享。端口类型、数据载体所有权和 acquire-release 调用顺序见 数据流转。

## 能力描述（capability）

能力描述（capability）是处理单元对外声明自身能力的机制。它不是单一的格式字段，而是一组可以被外部查询的能力节点：每个 `esp_gmf_cap_t` 用 `cap_eightcc` 标识能力类别，可附带性能信息 `perf` 和属性迭代函数 `attr_fun`。属性由 `esp_gmf_cap_attr_t` 描述，支持离散值、步进范围、倍数范围和常量值等形式。EIGHTCC 能力标识的定义见 系统工具，媒体格式的 FourCC 定义见 GMF FourCC。

处理单元通过 `ops.load_caps` 延迟加载能力列表。外部代码第一次调用 `esp_gmf_element_get_caps()` 时，框架会调用该回调并把结果缓存到处理单元对象中。典型实现如下：

    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;
    }

能力查询可以发生在注册池阶段，也可以发生在处理链构建后。应用或上层封装先遍历注册池中的处理单元模板，再读取每个处理单元的能力描述，按能力类别或属性范围选择合适的处理单元。例如视频处理链可以通过 `cap_eightcc` 查找具备缩放、裁剪、旋转等能力的处理单元；AI 音频处理链可以检查 ai_afe 是否同时声明 AEC、NS、AGC、VAD 等能力。

常用查询步骤如下：

1. 调用 `esp_gmf_element_get_caps()` 获取能力链表。

2. 调用 `esp_gmf_cap_fetch_node()` 按 `cap_eightcc` 找到某类能力。

3. 调用 `esp_gmf_cap_iterate_attr()` 或 `esp_gmf_cap_find_attr()` 获取能力属性。

4. 调用 `esp_gmf_cap_attr_check_value()` 判断目标值是否被支持。

属性类型用于描述不同的协商方式。离散属性适合列出若干个支持值，例如采样率或像素格式集合；步进属性适合描述最小值、最大值和步进，例如缩放后的宽高范围；倍数属性适合描述按因子变化的取值；常量属性适合描述固定能力。上层构建处理链时可据此做动态选择，减少写死处理单元名称和参数的逻辑。

## 运行时方法（method）

运行时方法（method）是处理单元对外暴露运行时控制动作的机制，用于 open / process / close 之外的参数设置或查询，例如设置目标采样率、调整音量、切换 EQ 预设、修改目标分辨率。每个 `esp_gmf_method_t` 包含方法名、执行函数和参数描述链表。

处理单元通过 `ops.load_methods` 延迟加载方法列表。外部代码调用 `esp_gmf_element_get_method()` 或 `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;
        /* 更新处理单元内部音量状态 */
        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;
    }

调用方按方法名执行：

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

方法名应保持稳定，参数描述用于告诉调用方参数名称、类型、大小和偏移。多个处理单元实现相同运行时方法名时，上层应用可以只依赖方法名而不依赖具体处理单元类型；例如软件重采样与硬件 ASRC 可以暴露相同的目标采样率设置方法，处理链替换处理单元后，上层调用逻辑保持不变。

## 自定义处理单元模板

下面给出一个最小音频处理单元骨架，把处理单元生命周期、数据端口属性和 acquire-release 调用串起来。该处理单元把输入 PCM 乘以增益因子后输出。

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

模板的要点：

- 自定义处理单元结构体把派生类基类放在第一个成员，便于在派生类与处理单元基类之间转换。

- 配置结构通过 `esp_gmf_obj_set_config` 绑定到对象，open 回调里通过 `OBJ_GET_CFG` 取出。

- 三个生命周期功能函数写在处理单元内部，构造时赋值到 `base->ops`。

- `dependency = true` 声明该处理单元需要上游格式信息才能启动。若处理逻辑不依赖上游格式，可保持默认值 false。

- process 中 `acquire_in` 与 `release_in`、`acquire_out` 与 `release_out` 严格成对；每个错误分支都要释放已 acquire 的数据载体，否则数据端口会泄漏。

- 输入数据载体的 `is_done` 需要按处理语义透传或转换；遇到流结束时返回 `DONE`，让框架把对应 job 从链表中移除。

构造好的处理单元可以注册到注册池，再由注册池按名称复制实例并构建处理链。处理链搭建与控制接口见 GMF 处理链与任务调度。

## API 参考

本篇涉及的头文件：

- `esp_gmf_element.h`：处理单元基类、生命周期、端口属性、能力描述与运行时方法访问接口

- `esp_gmf_audio_element.h` / `esp_gmf_video_element.h` / `esp_gmf_pic_element.h`：三类派生处理单元

- `esp_gmf_cap.h`：能力描述链表、属性描述与属性匹配

- `esp_gmf_method.h` / `esp_gmf_args_desc.h` / `esp_gmf_method_helper.h`：运行时方法描述、参数描述与辅助调用

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

  参数:

    - handle – [in] GMF element handle to initialize

    - config – [in] Pointer to the configuration structure

  返回:

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

  参数:

    handle – [in] GMF element handle to deinitialize

  返回:

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

  参数:

    - handle – [in] GMF element handle

    - cb – [in] Event callback function

    - ctx – [in] Context for the callback function

  返回:

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

  备注

  The registered port will be destroyed when `esp_gmf_element_unregister_out_port` is called

  参数:

    - handle – [in] GMF element handle

    - io_inst – [in] port handle to register

  返回:

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

  参数:

    - handle – [in] GMF element handle

    - io_inst – [in] Input port handle to unregister

  返回:

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

  备注

  The registered port will be destroyed when `esp_gmf_element_unregister_out_port` is called

  参数:

    - handle – [in] GMF element handle

    - io_inst – [in] Output port handle to register

  返回:

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

  参数:

    - handle – [in] GMF element handle

    - io_inst – [in] Output port handle to unregister

  返回:

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

  参数:

    - handle – [in] Given element handle

    - new_el – [in] New element handle to link

  返回:

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

  参数:

    - handle – [in] Given element handle

    - next_el – [in] Next element handle

  返回:

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

  参数:

    - handle – [in] Given element handle

    - prev_el – [in] Previous element handle

  返回:

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

  参数:

    - handle – [in] GMF element handle

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

  返回:

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

  参数:

    - handle – [in] GMF element handle

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

  返回:

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

  参数:

    - handle – [in] GMF element handle

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

  返回:

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

  参数:

    - handle – [in] GMF element handle

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

  返回:

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

  参数:

    - handle – [in] GMF element handle

    - new_state – [in] New state to set

  返回:

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

  参数:

    - handle – [in] GMF element handle

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

  返回:

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

  参数:

    handle – [in] GMF element handle

  返回:

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

  参数:

    handle – [in] GMF element handle

  返回:

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

  参数:

    - handle – [in] GMF element handle

    - event – [in] Pointer to the event packet

    - ctx – [in] Context for event processing

  返回:

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

  参数:

    - handle – [in] GMF element handle

    - mask – [in] Job mask to set

  返回:

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

  参数:

    - handle – [in] GMF element handle

    - mask – [in] Job mask to apply

  返回:

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

  参数:

    - handle – [in] GMF element handle

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

  返回:

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

  参数:

    - handle – [in] GMF element handle

    - info – [in] Pointer to sound information

  返回:

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

  参数:

    - handle – [in] GMF element handle

    - info – [in] Pointer to video information

  返回:

    - 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

  备注

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

  参数:

    - 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

  返回:

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

  参数:

    - 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`)

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

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

    - config – [in] Pointer to the configuration structure

  返回:

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

  参数:

    - handle – [in] GMF audio element handle

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

  返回:

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

  参数:

    - handle – [in] GMF audio element handle

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

  返回:

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

  参数:

    - handle – [in] GMF audio element handle

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

  返回:

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

  参数:

    - handle – [in] GMF audio element handle

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

  返回:

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

  参数:

    - handle – [in] GMF audio element handle

    - size – [in] New file size to update

  返回:

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

  参数:

    - handle – [in] GMF audio element handle

    - pos – [in] New file position to update

  返回:

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

  参数:

    handle – [in] GMF audio element handle to deinitialize

  返回:

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

  参数:

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

    - config – [in] Pointer to the configuration structure

  返回:

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

  参数:

    - handle – [in] GMF video element handle

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

  返回:

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

  参数:

    - handle – [in] GMF video element handle

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

  返回:

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

  参数:

    handle – [in] GMF video element handle to deinitialize

  返回:

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

  参数:

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

    - config – [in] Pointer to the configuration structure

  返回:

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

  参数:

    - handle – [in] GMF picture element handle

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

  返回:

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

  参数:

    - handle – [in] GMF picture element handle

    - value – [in] Pointer to the metadata value

    - len – [in] Length of the metadata value

  返回:

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

  参数:

    - handle – [in] GMF picture element handle

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

  返回:

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

  参数:

    - handle – [in] GMF picture element handle

    - info – [in] Pointer to the file information

  返回:

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

  参数:

    - handle – [in] GMF picture element handle

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

  返回:

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

  参数:

    - handle – [in] GMF picture element handle

    - info – [in] Pointer to the picture information

  返回:

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

  参数:

    - handle – [in] GMF picture element handle

    - size – [in] New file size to update

  返回:

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

  参数:

    - handle – [in] GMF picture element handle

    - pos – [in] New file position to update

  返回:

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

  参数:

    handle – [in] GMF picture element handle to deinitialize

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - iter – [inout] Pointer to the attribute

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

  返回:

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

  备注

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

  参数:

    - 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

  返回:

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

  备注

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

  参数:

    - 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

  返回:

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

  参数:

    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.

  参数:

    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.

  参数:

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

  返回:

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

  参数:

    - 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

  返回:

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

  备注

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

  参数:

    - 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

  返回:

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

  参数:

    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.

  参数:

    - 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

  返回:

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

  备注

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

  参数:

    - 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

  返回:

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

  备注

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

  参数:

    - 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

  返回:

    - 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

  参数:

    - 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

  返回:

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

  参数:

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

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

  返回:

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

  参数:

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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

    - 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

  返回:

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

  参数:

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

  参数:

    - method_head – [in] Header of GMF methods

    - method_name – [in] Method name to be searched

    - exec_ctx – [out] Pointer to method execution context

  返回:

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

  参数:

    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.

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。