obs-cpp-qt-patterns

OBS C++ 和 Qt 模式

目的

将 C++ 和 Qt6 集成到 OBS Studio 插件中，以实现设置对话框、前端 API 访问和丰富的 UI 组件。涵盖 CMake 配置、可选 Qt 构建和平台回退方案。

不适用场景

• 交叉编译 → 使用 obs-cross-compiling
• Windows 专用构建 → 使用 obs-windows-building
• 音频插件核心逻辑 → 使用 obs-audio-plugin-writing
• 代码审查 → 使用 obs-plugin-reviewing

快速入门：5 步创建 Qt 设置对话框

第 1 步：配置 CMake 以使用 Qt

cmake_minimum_required(VERSION 3.28)
project(my-plugin VERSION 1.0.0 LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Enable Qt automoc (REQUIRED for Qt classes with Q_OBJECT)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)

# Find Qt6 (optional)
find_package(Qt6 COMPONENTS Widgets QUIET)
if(Qt6_FOUND)
    message(STATUS "Qt6 found - building with settings dialog")
    set(BUILD_WITH_QT ON)
else()
    message(STATUS "Qt6 not found - building without settings dialog")
    set(BUILD_WITH_QT OFF)
endif()

第 2 步：有条件地添加 Qt 源文件

# Core plugin (C)
add_library(${PROJECT_NAME} MODULE
    src/plugin-main.c
    src/my-source.c
)

# Add Qt frontend (C++) if available
if(BUILD_WITH_QT)
    target_sources(${PROJECT_NAME} PRIVATE src/frontend.cpp)
    target_compile_definitions(${PROJECT_NAME} PRIVATE BUILD_WITH_QT)
    target_link_libraries(${PROJECT_NAME} PRIVATE Qt6::Widgets)

    # Link OBS frontend API
    find_package(obs-frontend-api QUIET)
    if(obs-frontend-api_FOUND)
        target_link_libraries(${PROJECT_NAME} PRIVATE OBS::obs-frontend-api)
    endif()
else()
    # Fallback: simple C frontend without dialog
    target_sources(${PROJECT_NAME} PRIVATE src/frontend-simple.c)
endif()

第 3 步：创建设置对话框类

// settings-dialog.h
#pragma once

#include <QDialog>
#include <QLineEdit>
#include <QSpinBox>
#include <QPushButton>
#include <QVBoxLayout>
#include <QFormLayout>

class SettingsDialog : public QDialog {
    Q_OBJECT

public:
    explicit SettingsDialog(QWidget *parent = nullptr);

    QString host() const { return m_hostEdit->text(); }
    int port() const { return m_portSpin->value(); }

    void setHost(const QString &host) { m_hostEdit->setText(host); }
    void setPort(int port) { m_portSpin->setValue(port); }

private:
    QLineEdit *m_hostEdit;
    QSpinBox *m_portSpin;
};

第 4 步：实现对话框

// settings-dialog.cpp
#include "settings-dialog.h"

SettingsDialog::SettingsDialog(QWidget *parent)
    : QDialog(parent)
{
    setWindowTitle(tr("Plugin Settings"));
    setMinimumWidth(300);

    // Create widgets
    m_hostEdit = new QLineEdit(this);
    m_hostEdit->setPlaceholderText(tr("127.0.0.1"));

    m_portSpin = new QSpinBox(this);
    m_portSpin->setRange(1, 65535);
    m_portSpin->setValue(5000);

    auto *okButton = new QPushButton(tr("OK"), this);
    auto *cancelButton = new QPushButton(tr("Cancel"), this);

    // Layout
    auto *formLayout = new QFormLayout;
    formLayout->addRow(tr("Host:"), m_hostEdit);
    formLayout->addRow(tr("Port:"), m_portSpin);

    auto *buttonLayout = new QHBoxLayout;
    buttonLayout->addStretch();
    buttonLayout->addWidget(okButton);
    buttonLayout->addWidget(cancelButton);

    auto *mainLayout = new QVBoxLayout(this);
    mainLayout->addLayout(formLayout);
    mainLayout->addLayout(buttonLayout);

    // Connections
    connect(okButton, &QPushButton::clicked, this, &QDialog::accept);
    connect(cancelButton, &QPushButton::clicked, this, &QDialog::reject);
}

第 5 步：与 OBS 前端 API 集成

// frontend.cpp
#include <obs-module.h>
#include <obs-frontend-api.h>

#ifdef BUILD_WITH_QT
#include "settings-dialog.h"
#include <QMainWindow>
#endif

extern "C" {

static void on_frontend_event(enum obs_frontend_event event, void *data)
{
    (void)data;

    switch (event) {
    case OBS_FRONTEND_EVENT_FINISHED_LOADING:
        /* OBS UI is ready - safe to create Qt widgets */
        break;
    default:
        break;
    }
}

void frontend_init(void)
{
    obs_frontend_add_event_callback(on_frontend_event, NULL);
}

void frontend_cleanup(void)
{
    obs_frontend_remove_event_callback(on_frontend_event, NULL);
}

void frontend_show_settings(void)
{
#ifdef BUILD_WITH_QT
    QMainWindow *main_window = (QMainWindow *)obs_frontend_get_main_window();

    SettingsDialog dialog(main_window);
    if (dialog.exec() == QDialog::Accepted) {
        /* Save settings */
        const char *host = dialog.host().toUtf8().constData();
        int port = dialog.port();
        /* Apply settings... */
    }
#else
    blog(LOG_INFO, "Settings dialog not available (Qt not built)");
#endif
}

} /* extern "C" */

OBS 前端 API

关键函数

函数	用途
obs_frontend_get_main_window()	获取 OBS 主窗口（作为 QMainWindow*）
obs_frontend_add_event_callback()	订阅前端事件
obs_frontend_remove_event_callback()	取消订阅事件
obs_frontend_add_tools_menu_item()	在“工具”菜单中添加项目
obs_frontend_add_dock()	添加可停靠面板

前端事件

enum obs_frontend_event {
    OBS_FRONTEND_EVENT_STREAMING_STARTING,
    OBS_FRONTEND_EVENT_STREAMING_STARTED,
    OBS_FRONTEND_EVENT_STREAMING_STOPPING,
    OBS_FRONTEND_EVENT_STREAMING_STOPPED,
    OBS_FRONTEND_EVENT_RECORDING_STARTING,
    OBS_FRONTEND_EVENT_RECORDING_STARTED,
    OBS_FRONTEND_EVENT_RECORDING_STOPPING,
    OBS_FRONTEND_EVENT_RECORDING_STOPPED,
    OBS_FRONTEND_EVENT_SCENE_CHANGED,
    OBS_FRONTEND_EVENT_SCENE_LIST_CHANGED,
    OBS_FRONTEND_EVENT_TRANSITION_CHANGED,
    OBS_FRONTEND_EVENT_FINISHED_LOADING,
    OBS_FRONTEND_EVENT_EXIT,
    /* ... more events */
};

添加“工具”菜单项目

static void on_tools_menu_clicked(void *data)
{
    (void)data;
    frontend_show_settings();
}

void frontend_init(void)
{
    obs_frontend_add_tools_menu_item(
        obs_module_text("MyPlugin.Settings"),  /* Menu text */
        on_tools_menu_clicked,                  /* Callback */
        NULL                                    /* User data */
    );
}

Qt 可选构建模式

CMake 配置

# Try to find Qt6, but don't fail if missing
find_package(Qt6 COMPONENTS Widgets QUIET)

if(Qt6_FOUND)
    set(BUILD_WITH_QT ON)
    message(STATUS "Qt6 found - building with UI")
else()
    set(BUILD_WITH_QT OFF)
    message(STATUS "Qt6 not found - building without UI")
endif()

# Conditional compilation
if(BUILD_WITH_QT)
    target_sources(${PROJECT_NAME} PRIVATE
        src/frontend.cpp
        src/settings-dialog.cpp
    )
    target_compile_definitions(${PROJECT_NAME} PRIVATE BUILD_WITH_QT)
    target_link_libraries(${PROJECT_NAME} PRIVATE Qt6::Widgets)
else()
    target_sources(${PROJECT_NAME} PRIVATE
        src/frontend-simple.c
    )
endif()

C 回退方案（frontend-simple.c）

/* frontend-simple.c - Minimal frontend without Qt
 *
 * Used when Qt is not available (e.g., cross-compilation).
 */

#include <obs-module.h>

void frontend_init(void)
{
    blog(LOG_INFO, "Plugin loaded without Qt UI");
}

void frontend_cleanup(void)
{
    /* Nothing to clean up */
}

void frontend_show_settings(void)
{
    blog(LOG_WARNING, "Settings dialog not available (Qt not built)");
}

头文件模式

/* frontend.h - Frontend API (C-compatible) */
#pragma once

#ifdef __cplusplus
extern "C" {
#endif

void frontend_init(void);
void frontend_cleanup(void);
void frontend_show_settings(void);

#ifdef __cplusplus
}
#endif

C 和 C++ 混合模式

extern "C" 包装器

// In C++ files that expose C API:
extern "C" {

#include <obs-module.h>

void my_cpp_function(void)
{
    // C++ code here
}

} /* extern "C" */

在 C++ 中使用 C 头文件

// Always use extern "C" when including C headers from C++
extern "C" {
#include <obs-module.h>
#include <obs-frontend-api.h>
}

// Now safe to use C++ features
#include <QString>

插件主文件（使用 C++ 特性的 C 文件）

/* plugin-main.c - C module entry point */

#include <obs-module.h>
#include "frontend.h"  /* C-compatible header */

OBS_DECLARE_MODULE()
OBS_MODULE_USE_DEFAULT_LOCALE("my-plugin", "en-US")

bool obs_module_load(void)
{
    obs_register_source(&my_source);

    /* Initialize frontend (may be C or C++) */
    frontend_init();

    return true;
}

void obs_module_unload(void)
{
    frontend_cleanup();
}

CMAKE_AUTOMOC 说明

AUTOMOC 的作用

• 扫描 C++ 文件中的 Q_OBJECT 宏
• 自动运行 Qt 的 moc（元对象编译器）
• 为信号/槽支持生成 moc_*.cpp 文件

必需的设置

set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)  # For .ui files

# AUTOMOC requires C++ targets
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

常见问题

问题	原因	解决方案
"undefined reference to vtable"	缺少 Q_OBJECT	将 Q_OBJECT 添加到类中
"moc not found"	Qt 不在 PATH 中	使用 find_package(Qt6)
"undefined signal/slot"	AUTOMOC 未运行	确保 .h 位于 SOURCES 中

使用 Qt 进行线程处理

安全的线程通信

// worker-thread.cpp
#include <QThread>
#include <QObject>

class WorkerThread : public QThread {
    Q_OBJECT

signals:
    void resultReady(const QString &result);

protected:
    void run() override {
        QString result = doWork();
        emit resultReady(result);  /* Signal is thread-safe */
    }

private:
    QString doWork() {
        /* Heavy work here */
        return "Done";
    }
};

// Usage from main thread:
WorkerThread *thread = new WorkerThread;
connect(thread, &WorkerThread::resultReady, this, &MyClass::handleResult);
connect(thread, &WorkerThread::finished, thread, &QObject::deleteLater);
thread->start();

Qt 事件循环集成

// Don't block OBS main thread - use async patterns
void MyDialog::onButtonClicked()
{
    // WRONG: Blocks OBS UI
    // QThread::sleep(5);

    // CORRECT: Use QTimer or worker thread
    QTimer::singleShot(0, this, [this]() {
        // Runs after current event processing
        doSomething();
    });
}

禁止的模式

模式	问题	解决方案
在 UI 回调中阻塞	OBS 冻结	使用工作线程
缺少 Q_OBJECT	信号/槽失效	添加 Q_OBJECT 宏
在音频线程中使用 Qt 控件	崩溃	仅在主线程中使用 UI
混用 Qt 版本	ABI 问题	仅使用 Qt6
缺少 AUTOMOC	链接错误	启用 CMAKE_AUTOMOC
未检查就直接调用 obs_frontend 函数	没有前端时会崩溃	检查 obs-frontend-api_FOUND

平台专用 UI 回退方案

Windows 原生对话框

/* settings-dialog-win32.c - Fallback when Qt unavailable */
#ifdef _WIN32
#include <windows.h>
#include <commctrl.h>

void show_settings_dialog_win32(void *parent)
{
    MessageBoxW((HWND)parent,
                L"Settings dialog requires Qt.\nPlease install Qt6.",
                L"Plugin Settings",
                MB_OK | MB_ICONINFORMATION);
}
#endif

CMake 平台选择

if(NOT BUILD_WITH_QT)
    if(WIN32)
        target_sources(${PROJECT_NAME} PRIVATE
            src/settings-dialog-win32.c
        )
    else()
        target_sources(${PROJECT_NAME} PRIVATE
            src/frontend-simple.c
        )
    endif()
endif()

外部文档

Context7

mcp__context7__query-docs
libraryId: "/obsproject/obs-studio"
query: "Qt frontend API settings dialog"

官方参考资料

• OBS 前端 API：https://docs.obsproject.com/reference-frontend-api
• Qt6 Widgets：https://doc.qt.io/qt-6/qtwidgets-index.html
• CMake AUTOMOC：https://cmake.org/cmake/help/latest/prop_tgt/AUTOMOC.html

相关技能

• obs-windows-building - Windows 专用构建
• obs-cross-compiling - 交叉编译（可能不包含 Qt）
• obs-plugin-developing - 插件架构概览
• obs-audio-plugin-writing - 音频插件实现

相关 Agent

使用 obs-plugin-expert，获取跨所有 OBS 插件技能的协调指导。