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 等能力。

常用查询步骤如下：

调用 esp_gmf_element_get_caps() 获取能力链表。
调用 esp_gmf_cap_fetch_node() 按 cap_eightcc 找到某类能力。
调用 esp_gmf_cap_iterate_attr() 或 esp_gmf_cap_find_attr() 获取能力属性。
调用 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.

此文档对您有帮助吗？

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

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