在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

obsproject/obs-studio

菜单

属性系统

相关源文件

OBS Studio 中的属性系统提供了一种平台无关的方式来定义 OBS 组件（来源、滤镜、编码器等）的可配置设置。它弥合了核心功能与用户界面之间的鸿沟，允许组件指定设置，这些设置可由前端显示和修改，而无需绑定到任何特定的 UI 工具包。

本文档涵盖属性系统的内部架构和使用。有关设置对话框的 UI 实现信息，请参阅前端 API 文档。

架构概述

属性系统由以下关键组件组成

来源: libobs/obs-properties.h22-126 libobs/obs-properties.c177-205

其核心，属性系统包括

  • obs_properties_t: 形成设置面板的属性集合
  • obs_property_t: 单个属性元素（布尔值、文本字段、下拉列表等）
  • 修改回调：允许动态属性行为的函数

这种架构将组件逻辑与 UI 考量分离，使 OBS 能够在不同平台间一致地呈现配置界面。

属性结构和类型

单个属性（obs_property_t）具有以下结构

来源: libobs/obs-properties.c180-194

系统支持各种属性类型，以适应不同的设置需求

属性类型描述创建函数
布尔值简单复选框obs_properties_add_bool()
整型数字输入（滑块或微调器）obs_properties_add_int()
浮点数浮点数输入obs_properties_add_float()
文本文本输入框obs_properties_add_text()
路径文件/目录选择器obs_properties_add_path()
列表下拉/组合框obs_properties_add_list()
颜色颜色选择器obs_properties_add_color()
按钮可点击动作按钮obs_properties_add_button()
字体字体选择器obs_properties_add_font()
可编辑列表带添加/删除/编辑功能的列表obs_properties_add_editable_list()
帧率帧率选择obs_properties_add_frame_rate()
分组其他属性的容器obs_properties_add_group()

来源: libobs/obs-properties.h45-60 libobs/obs-properties.c397-434

创建属性

创建属性的典型模式遵循以下流程

来源: libobs/obs-properties.c207-246 libobs/obs-properties.c436-452

创建属性的关键步骤

  1. 使用obs_properties_create()创建属性容器
  2. 使用obs_properties_add_xxx()函数添加属性
  3. 配置属性的限制、描述及其他属性
  4. 如果需要动态行为，设置修改回调
  5. 将容器返回给 UI 进行渲染

动态属性行为

属性系统通过回调支持动态 UI

来源: libobs/obs-properties.c792-818 251-254

回调使属性能够

  • 根据值显示/隐藏其他属性
  • 启用/禁用其他属性
  • 更改描述或限制
  • 动态更新列表内容
  • 添加/删除属性（并相应刷新 UI）

属性存储和检索

虽然属性定义了 UI，但实际值存储在 obs_data_t 对象中

来源: libobs/obs-properties.c376-396 libobs/obs-properties.h162-163

这种分离允许

  • 值独立于 UI 进行保存/加载
  • 提供默认值
  • 设置在会话之间持久化
  • 组件验证和处理设置

与 OBS 组件集成

属性系统通过特定函数与 OBS 组件集成

来源: docs/sphinx/reference-modules.rst41-55

典型的集成流程

  1. 组件实现一个返回 obs_properties_t 对象的 get_properties() 函数
  2. 前端将这些属性渲染为 UI 控件
  3. 当值发生更改时，存储在 obs_data_t 对象中
  4. 调用组件的 update() 函数并传入新设置
  5. 组件将其内部状态应用设置

属性修改流程

当属性更改时，OBS 处理更新流程

来源: libobs/obs-properties.c376-396 libobs/obs-properties.c792-818

常见属性类型详解

列表属性

列表属性（组合框）提供多种格式和类型

来源: libobs/obs-properties.h62-75 libobs/obs-properties.c599-619

分组属性

分组允许将属性组织成逻辑部分

来源: libobs/obs-properties.h107-111 libobs/obs-properties.c732-757

结论

属性系统提供了一种灵活、独立于工具包的方式来定义 OBS 组件的可配置设置。通过将设置的定义与其表示和存储分离，OBS 实现了统一的配置体验，同时允许组件保持对其设置的控制。

该系统是 OBS 扩展性的关键部分，使插件和核心组件能够与用户界面无缝集成，而无需实现自己的 UI 代码。

来源: libobs/obs-properties.h22-37