LuYishan Blog

KDE-Wayland插件開發

Sun, 30 Aug 2026 00:00:00 GMT

如何開發 KWin 插件#

KWin 是 KDE Plasma 桌面環境內建的視窗合成器與視窗管理員，支援在 X11 與 Wayland 兩種顯示協定下運作。KWin 提供了相當彈性的插件架構，讓開發者能在不修改核心程式碼的情況下擴充功能，例如特效（Effects）、腳本（Scripts）、視窗裝飾（Window Decorations）等。本文將介紹兩種主要的開發方式：KWin Scripts（QML/JavaScript） 與 KWin C++ 原生插件（Effects/Plugins）。

一、開發方式概覽#

KWin 的擴充機制大致分為三類：

KWin Scripts：使用 JavaScript 撰寫，透過 KWin 提供的腳本 API 操作視窗、工作區、輸出裝置等，開發門檻低，適合快速原型與簡易自動化邏輯。
KWin Effects（特效插件）：使用 C++ 撰寫，可直接存取合成器的渲染管線，適合實作視覺特效（如模糊、縮放動畫、轉場效果）。
視窗裝飾（Decoration）插件：使用 C++ 與 QML 撰寫，用來自訂視窗標題列、按鈕樣式等外觀。

以下分別說明前兩種最常見的開發方式。

二. 撰寫 metadata.json#

metadata.json 定義插件的基本資訊，KWin 會依此辨識並載入腳本：

1
{
2
    "KPlugin": {
3
        "Id": "my-kwin-script",
4
        "Name": "My KWin Script",
5
        "Description": "示範用的 KWin 腳本插件",
6
        "Authors":  "你的名字",
7
        "Version": "1.0",
8
        "License": "GPL-3.0-or-later"
9
    }
10
}

三、開發 KWin Effect（C++ 原生特效插件）#

1. 環境需求#

KDE Frameworks（KF6）與 Qt6 開發套件
KWin 原始碼與標頭檔（建議使用發行版提供的 kwin-devel 或自行編譯 KWin）
CMake、extra-cmake-modules

2. 基本 CMakeLists.txt 範例#

1
cmake_minimum_required(VERSION 3.19)
2
project({your_project_name} VERSION 6.0.0 LANGUAGES CXX)
3

4
set(CMAKE_CXX_STANDARD 20)
5
set(CMAKE_CXX_STANDARD_REQUIRED ON)
6
find_package(ECM 6.0.0 REQUIRED NO_MODULE)
7
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
8

9
include(KDEInstallDirs)
10
include(KDECMakeSettings)
11
include(KDECompilerSettings NO_POLICY_SCOPE)
12

13
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
14
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
15
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
16

17
set(QT_NO_CREATE_VERSIONLESS_FUNCTIONS TRUE)
18
find_package(Qt6 REQUIRED COMPONENTS Core Gui Network Widgets)
19
find_package(KF6 REQUIRED COMPONENTS CoreAddons)
20
find_package(KWin REQUIRED)
21

22
set(project_SRCS
23
    main.cpp
24
)
25

26
kcoreaddons_add_plugin({your_project_name}
27
    SOURCES ${project_SRCS}
28
    INSTALL_NAMESPACE "kwin/effects/plugins"
29
)
30

31
target_link_libraries({your_project_name}
32
    Qt::Core
33
    Qt::Gui
34
    Qt::Network
35
    KF6::CoreAddons
36
    KWin::kwin
37
)

展開收起

3. 示範#

workspace_tracker.hpp展開收起

1
#pragma once
2

3
#include <effect/effect.h>
4
#include <effect/effecthandler.h>
5
#include <QLocalSocket>
6
#include <QPointer>
7
#include <QObject>
8
#include <QPointF>
9
#include <kwin/virtualdesktops.h>
10

11
namespace kde {
12

13
struct DesktopTransition {
14
    int desktop;
15
    float x;
16
    float y;
17
};
18

19
class WorkspaceTrackerEffect : public KWin::Effect
20
{
21
    Q_OBJECT
22
public:
23
    WorkspaceTrackerEffect();
24
    ~WorkspaceTrackerEffect() override;
25

26
private Q_SLOTS:
27
    void onDesktopChanging(KWin::VirtualDesktop* desktop, QPointF offset);
28
    void onDesktopChangingCancelled();
29
    void onDesktopChanged(KWin::VirtualDesktop* oldDesktop, KWin::VirtualDesktop* newDesktop);
30
    void connectSocket();
31

32
private:
33
    void sendPayload(int desktop, float x, float y);
34

35
    QLocalSocket* m_socket;
36
};
37

38
} // namespace caelestia

展開收起

workspace_tracker.cpp展開收起

1
#include "workspace_tracker.hpp"
2
#include <QTimer>
3
#include <KPluginFactory>
4
#include <QStandardPaths>
5
#include <QDir>
6
#include <QDebug>
7
#include <QStandardPaths>
8
#include <QDir>
9

10
namespace kde {
11

12
WorkspaceTrackerEffect::WorkspaceTrackerEffect()
13
    : m_socket(new QLocalSocket(this))
14
{
15
    connect(KWin::effects, &KWin::EffectsHandler::desktopChanging,
16
            this, &WorkspaceTrackerEffect::onDesktopChanging);
17
    connect(KWin::effects, &KWin::EffectsHandler::desktopChangingCancelled,
18
            this, &WorkspaceTrackerEffect::onDesktopChangingCancelled);
19
    connect(KWin::effects, &KWin::EffectsHandler::desktopChanged,
20
            this, &WorkspaceTrackerEffect::onDesktopChanged);
21

22
    connect(m_socket, &QLocalSocket::disconnected, this, [this]() {
23
        qDebug() << "WorkspaceTracker: Socket disconnected, retrying...";
24
        QTimer::singleShot(2000, this, &WorkspaceTrackerEffect::connectSocket);
25
    });
26

27
    connect(m_socket, &QLocalSocket::errorOccurred, this, [this](QLocalSocket::LocalSocketError err) {
28
        qDebug() << "WorkspaceTracker: Socket error:" << err << "- retrying in 2s";
29
        QTimer::singleShot(2000, this, &WorkspaceTrackerEffect::connectSocket);
30
    });
31

32
    connect(m_socket, &QLocalSocket::connected, this, [this]() {
33
        qDebug() << "WorkspaceTracker: Socket connected!";
34
    });
35

36
    connectSocket();
37
}
38

39
WorkspaceTrackerEffect::~WorkspaceTrackerEffect()
40
{
41
    if (m_socket->isOpen()) {
42
        m_socket->close();
43
    }
44
}
45

46
void WorkspaceTrackerEffect::connectSocket()
47
{
48
    if (m_socket->state() == QLocalSocket::UnconnectedState) {
49
        QString socketPath = QStandardPaths::writableLocation(QStandardPaths::RuntimeLocation) + QStringLiteral("/caelestia-workspace-tracker");
50
        qDebug() << "WorkspaceTracker: Connecting to socket:" << socketPath;
51
        m_socket->connectToServer(socketPath);
52
    }
53
}
54

55
void WorkspaceTrackerEffect::sendPayload(int desktop, float x, float y)
56
{
57
    if (m_socket->state() == QLocalSocket::ConnectedState) {
58
        DesktopTransition payload{desktop, x, y};
59
        m_socket->write(reinterpret_cast<const char*>(&payload), sizeof(payload));
60
    }
61
}
62

63
void WorkspaceTrackerEffect::onDesktopChanging(KWin::VirtualDesktop* desktop, QPointF offset)
64
{
65
    if (desktop && m_socket->state() == QLocalSocket::ConnectedState) {
66
        qDebug() << "WorkspaceTracker: sending offset" << offset << "for desktop" << desktop->x11DesktopNumber();
67
        sendPayload(desktop->x11DesktopNumber(), static_cast<float>(offset.x()), static_cast<float>(offset.y()));
68
    } else {
69
        qDebug() << "WorkspaceTracker: not connected or desktop is null. Socket state:" << m_socket->state();
70
    }
71
}
72

73
void WorkspaceTrackerEffect::onDesktopChangingCancelled()
74
{
75
    sendPayload(0, 0.0f, 0.0f);
76
}
77

78
void WorkspaceTrackerEffect::onDesktopChanged(KWin::VirtualDesktop* oldDesktop, KWin::VirtualDesktop* newDesktop)
79
{
80
    if (newDesktop && m_socket->state() == QLocalSocket::ConnectedState) {
81
        sendPayload(newDesktop->x11DesktopNumber(), 0.0f, 0.0f);
82
    }
83
}
84

85
} // namespace kde
86

87
KWIN_EFFECT_FACTORY(kde::WorkspaceTrackerEffect, "metadata.json") //要記得有他就好:)
88

89
#include "workspace_tracker.moc"

展開收起

特效插件可覆寫 paintScreen()、paintWindow() 等函式來介入合成器的繪製流程，實作模糊、透明度漸變、位移動畫等效果。

4. 編譯與安裝#

Terminal window

1
mkdir build && cd build
2
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
3
make
4
sudo make install

安裝完成後，於系統設定的「桌面特效」清單中應可看到新插件並啟用。

四、除錯建議#

使用 journalctl --user -f | grep kwin (若在程式碼用qDebug()的話)來觀察log 與錯誤訊息。
修改 C++ 插件後務必重新編譯並重啟 KWin（或登出重登），避免載入到舊版本的動態函式庫。

五、參考資源#

KDE 官方開發者文件（develop.kde.org）中的 KWin 章節
KWin 原始碼倉庫內的 src/scripting/ 與 src/effects/ 目錄，內含大量官方特效與腳本範例可供參考
KDE Bugzilla 與 invent.kde.org 上的 KWin 專案，可觀察社群提交的合併請求（Merge Request）學習實際開發流程

當然你也可以來給我的垃圾專案星星https://github.com/LuYishan-4/Animated_UltralightWeb_Cursor

OpenGL如何使用自製glad

Sun, 30 Aug 2026 00:00:00 GMT

為什麼需要 glad？#

OpenGL 本身只是一份「規格」（specification），實際的函式進入點（function pointer）必須在執行期由驅動程式提供，作業系統只會內建非常舊版本的 OpenGL 標頭（例如 Windows 只內建到 OpenGL 1.1）。如果想使用比較新的 OpenGL 版本或擴充功能（extension），就必須自己在程式啟動時，透過 wglGetProcAddress / glXGetProcAddress 之類的函式，把每一個新函式的位址抓出來。

這件事如果手動做非常繁瑣，而且每個平台的作法都不一樣，於是就有了「OpenGL Loader Generator」這類工具，glad 就是其中最常見、使用度最高的一款。

glad 是什麼#

glad 是由 Dav1dde 開發的一個 loader 產生器，它會直接讀取 Khronos 官方釋出的 XML 規格檔，依照你指定的 API、版本與擴充功能，「客製化」產生出對應的載入程式碼（source + header）。

它的特色大致如下：

支援多種圖形 API：OpenGL、OpenGL ES、EGL、GLX、WGL，新版（glad2）甚至加入了 Vulkan
支援多種語言：C/C++、D、Nim、Pascal、Volt 等
因為是直接從官方 XML 規格產生，正確性與更新速度都有保障
提供線上網頁生成器

glad.dav1d.de：線上生成器#

https://glad.dav1d.de/ 是 glad 專案官方提供的網頁版生成器，對大多數只想「產生一份 glad 檔案來用」的人來說，完全不需要安裝 Python 版的 glad，直接在網頁上勾選好選項、按下產生按鈕，下載 zip 即可。

進入頁面後會看到幾個區塊：

1. Language（輸出語言）#

決定產生出來的程式碼是哪種語言，選項包含：

C/C++：最常用，也是絕大多數 OpenGL 教學採用的版本
C/C++ Debug：在一般 C/C++ 版本的基礎上加入除錯用的包裝（wrapper），每次呼叫 OpenGL 函式前後都會插入額外檢查（例如自動呼叫 glGetError），方便開發階段抓錯，但效能會比正式版差一些
D / Volt / Nim / Pascal：給使用這些語言開發的人使用

一般使用 C/C++ 開發、正式發布時，選 C/C++ 即可；開發階段想抓 OpenGL 錯誤，可以先用 C/C++ Debug 版本。

2. Specification（規格 / API）#

這裡選的是你要用哪一套圖形 API 規格，包含：

OpenGL (gl)：桌面版 OpenGL，也是最常見的選擇
EGL：用來在各平台（尤其是嵌入式、行動裝置、Linux 上不透過 GLX/WGL）建立繪圖 context 的介面
GLX：Linux/X11 平台下，讓 OpenGL 與視窗系統溝通的介面
WGL：Windows 平台下，讓 OpenGL 與視窗系統溝通的介面

大部分情況下，只需要勾選 gl（OpenGL 本體）；如果你是透過 GLFW、SDL 等函式庫來開窗，視窗系統相關的 context 建立已經被這些函式庫包好了，通常不需要額外勾 EGL / GLX / WGL，而且另外講一下若你之後會開發像Kwin插件那類直接在系統的不需要用到glad跟創glfw因爲它本身已經創好了。

3. API 版本（Version）#

每個 API 下面會列出可選的版本號，例如 gl 從 1.0 一路到目前最新的 4.6。這裡的邏輯是：選了某個版本，glad 就會把「該版本以前（含）所有核心函式」都包進去，版本越高涵蓋的函式越多。

實務上的建議：

不確定要用到多新的功能時，選 4.6（目前桌面 OpenGL 的最新版）最保險，之後程式裡只呼叫你用得到的函式即可，不會有額外負擔
如果目標平台比較舊（例如某些教學或相容性考量），才需要刻意選較低版本，例如 3.3

4. Profile（描述檔）#

這是 OpenGL 3.2 之後才有的概念，只影響 gl 這個 API：

Core：只包含現代、精簡的固定管線之後的 API，移除掉舊式（fixed-function pipeline，例如 glBegin/glEnd）的函式。現在幾乎所有新專案、教學都建議用這個
Compatibility：向下相容，保留舊版固定管線的函式，通常只有在需要與舊程式碼相容，或某些教學特別要求時才會用

一般新專案的建議：Core。

5. Extensions（擴充功能）#

這一大串清單就是所有 Khronos 登記在案的擴充功能（例如 GL_ARB_*、GL_EXT_*、GL_NV_* 等），代表某些顯示卡廠商或延伸規格額外提供、還沒被收進核心版本的功能。

常見會另外勾選的擴充（也就是說明裡提到的「常見安裝擴充」）：

GL_ARB_texture_filter_anisotropic（或舊版的 GL_EXT_texture_filter_anisotropic）：非等向性過濾，改善貼圖在斜角觀看時的清晰度
GL_ARB_debug_output / GL_KHR_debug：提供更完整的除錯訊息回呼機制，開發階段非常實用
GL_ARB_direct_state_access：DSA，讓你不用先 bind 物件就能直接操作，能簡化不少程式碼
GL_ARB_bindless_texture：bindless 貼圖，進階效能優化才會用到

不確定要不要勾，通常的原則是：先不要全選（全選會讓產生的檔案變得龐大、也會失去 glad「客製化、輕量」的意義），等到專案真的需要某個擴充功能時，再回來這裡加選、重新產生即可。

6. Options（其他選項）#

Generate a loader：勾選後才會產生 gladLoadGL() 這類「初始化 / 載入所有函式指標」的程式碼；如果你已經有自己的載入邏輯，可以不勾，只拿函式宣告
Omit KHR：省略 KHR 平台標頭（khrplatform.h），適合已經有自己一份 khrplatform.h、或用某些精簡環境時使用；官方註記這個選項可能因規格變動而不一定能正常運作
Local files：使用本機快取的規格檔而非即時下載最新版，主要差異在於「產生速度」與「規格新舊」

實際使用流程#

打開 glad.dav1d.de
Language 選 C/C++
Specification 只勾 gl，版本選你需要的（例如 4.6）
Profile 選 Core
Extensions 依需求加選（不確定就先不加）
Options 記得勾 Generate a loader
按下 GENERATE，下載產生出來的壓縮檔
把裡面的 include/ 和 src/glad.c 加進你的專案，並確保 #include <glad/glad.h> 在任何其他 OpenGL 相關標頭（例如 GLFW）之前引入
在建立好繪圖 context 之後，呼叫產生的載入函式，例如：

1
#include <glad/glad.h>
2
#include <GLFW/glfw3.h>
3

4
int main(void) {
5
    // ... 建立視窗與 context ...
6
    glfwMakeContextCurrent(window);
7

8
    if (!gladLoadGLLoader((GLADloadproc)glfwGetProcAddress)) {
9
        printf("Failed to initialize GLAD\n");
10
        return -1;
11
    }
12

13
    printf("Loaded OpenGL %d.%d\n", GLVersion.major, GLVersion.minor);
14
    // ... 開始使用 OpenGL 函式 ...
15
}

展開收起

小結#

glad 本身：一個依規格「客製化產生」OpenGL/EGL/GLX/WGL 載入程式碼的工具
glad.dav1d.de：官方提供的免安裝網頁版生成器
選項核心邏輯：Language（輸出語言）→ Specification + Version（要哪個 API、多新的版本）→ Profile（Core / Compatibility）→ Extensions（額外擴充功能）→ Options（要不要產生 loader、省略檔案等）
新專案的推薦組合：C/C++、gl、最新版本（如 4.6）、Core、視需求加擴充、勾選 Generate a loader

第一篇

Sat, 29 Aug 2026 00:00:00 GMT

嗨#

6767676