common

common

Go 跨平台基础库集合，面向游戏 / 实时应用与通用后端场景。
模块路径：github.com/liuqi0826/common（Go 1.26+）。

多数平台绑定通过 动态库 / syscall 完成，不依赖 CGO（CGO_ENABLED=0 即可构建与测试）。许可证：MIT。

项目定位

领域对象普遍嵌入 events.EventDispatcher（如 window.Window、network.Connector），用 AddEventListener 收业务事件；构造统一使用接收者上的 Constructor（调用方先分配：var x T / x := &T{}，再 x.Constructor(...)），不用包级 Create* / 惯用 New*。方法接收者命名为 this。WebGPU / Win32 等与规范同名的 Create* API 除外。

包一览

架构关系（简图）

                    ┌──────────── events ────────────┐
                    │  EventDispatcher / 事件常量     │
                    └───────────┬────────────────────┘
          ┌─────────────────────┼─────────────────────┐
          ▼                     ▼                     ▼
   system/window          network.Connector         （其它宿主）
   （输入 KEY_*/MOUSE_*…） （CLOSE / IO_ERROR…）
          │
          ├─ SurfaceDescriptor ──► gpu/webgpu
          ├─ SetCursor ◄────────── system/cursor
          │
   system/monitor · clipboard     （独立，不依赖 window）

   platform/dl ◄── gpu / apu / window 等平台绑定

快速开始

# 建议关闭 CGO
$env:CGO_ENABLED=0   # Windows PowerShell
# export CGO_ENABLED=0

go test ./format/audio/
go test ./format/image/
go test ./system/window/ ./system/monitor/ ./system/clipboard/ ./system/cursor/

go run ./database/examples/sqlite
go run ./network/examples/echo
go run ./apu/examples/beep
go run ./gpu/examples/triangle
go run ./system/window/examples/watch

import (
    "github.com/liuqi0826/common/events"
    "github.com/liuqi0826/common/system/window"
)

w := &window.Window{}
if err := w.Constructor(window.Config{Title: "demo", Width: 800, Height: 600}); err != nil {
    panic(err)
}
window.DefaultManager().Attach(w)
defer w.Close()

w.AddEventListener(events.KEY_DOWN, func(e *events.Event) {
    // e.Data.(*events.KeyboardEventData)
}, nil)

for !w.ShouldClose() {
    w.PollEvents(nil)
}

子模块说明

events

EventDispatcher.Constructor(host)：同步分发，按 type + target 管理监听。
常量见 events/const.go，按域分区：

数据载荷见 events/event_data.go。

format（媒体编解码）

与 apu（播放）、gpu（渲染）解耦，负责文件字节 ↔ 结构化数据。

format/audio：Sniff / Decode / Encode，中间表示为 planar float32 PCM。

pcm, _, err := audio.Decode(data)
out, err := audio.Encode(pcm, audio.FormatWAV, audio.DefaultEncodeOptions())

format/image（包名 imgfmt）：Sniff / Decode / Encode，中间表示为 RGBA8 RGBA（行优先、自上而下）。

* Decode 对 GIF 仅取第一帧；动画请用 DecodeGIF。

import imgfmt "github.com/liuqi0826/common/format/image"

img, _, err := imgfmt.Decode(data)
out, err := imgfmt.Encode(img, imgfmt.FormatPNG, imgfmt.DefaultEncodeOptions())

go run ./format/image/examples/convert ./input.webp ./output.png

system（窗口与桌面能力）

system/window（Win32 / X11 / Cocoa / Canvas）

• 构造：Window.Constructor(cfg) / ConstructorDetached()，再 Manager.Attach（或 Register）
• 多窗：Manager / Focused / PollAll / Broadcast / DispatchToFocused
• 窗控（对齐 GLFW）：ShouldClose、SetTitle、SetSize、Position、Show/Hide、Iconify/Maximize/Restore、Focus、RequestAttention、FramebufferSize
• 输入：窗口本体派发 KEY_* / MOUSE_* / POINTER_* / TOUCH_* / IME_* / GAMEPAD_*；Inject* 仿真；PollGamepads（Windows XInput）
• GPU：SurfaceDescriptor()

独立包（不依赖 window）

• system/monitor：GetMonitors / GetPrimaryMonitor
• system/clipboard：GetString / SetString
• system/cursor：Cursor.Constructor(shape)；窗口侧 SetCursor / SetCursorMode

go run ./system/window/examples/watch
go run ./system/window/examples/inject
go run ./system/window/examples/manager

gpu

纯 Go WebGPU 风格图形层。公共 API：gpu/webgpu；着色：gpu/wgsl（WGSL → HLSL / MSL / SPIR-V）。
后端：D3D12（Windows）、Vulkan（Windows/Linux）、Metal（macOS）、浏览器 WebGPU（WASM）。
详情与能力矩阵见 gpu/README.md、gpu/STATUS.md。

go run ./gpu/examples/triangle
go run ./gpu/examples/vertex
go run ./gpu/examples/uniform
go run ./gpu/examples/compute

apu

Web Audio 风格音频处理图（Oscillator / Gain / BufferSource / 基础 FX）。
输出：WASAPI、ALSA、OpenAL、AAudio、WASM 等（均无 CGO）。
文件解码不在本包实现：format/audio 负责编解码；apu.DecodeAudioData / BufferFromPCM 仅为播放桥接。

go run ./apu/examples/beep
go run ./apu/examples/poly100
go run ./apu/examples/play_wav   # WAV / MP3 / FLAC / OGG / AIFF

network

DialTCP|UDP|WS|Chan + Listen*，统一 Connector（收发、可选心跳、嵌入 events）。
示例：echo / chan / ws。详见 network/doc.go。

database

• SQL：OpenMySQL / OpenSQLite / OpenPostgres，InTx、健康检查、可选重连；Migrate / Scan
• KV：MemoryKV.Constructor()、OpenRedis / OpenLevelDB，KVBatch
• 示例：sqlite / migrate / kv / remote（remote 需环境变量）

geom

Vector / Matrix / Quaternion、曲线、各类 Shape 与相交测试；amd64 可选 SIMD。矩阵/平面用 Constructor* 初始化。

platform/dl

跨平台 dlopen / LoadLibrary 风格加载与符号解析，供 gpu / apu / window 等使用。

utils

slog.New（文本/JSON Handler）、TokenManager.Constructor / TokenID、字符串与字节工具、Retry、Map / Pool / ErrGroup / OnceValue 等。

约定

1. 构造：领域类型用 (this *T) Constructor(...)（调用方分配）；连接类保留 Open* / Dial* / Listen*；不用包级 Create* / New*（WebGPU / OS API 同名方法除外）。
2. 事件：可分发对象嵌入 events.EventDispatcher，host 作为默认 Event.Target。
3. 接收者：公开方法命名接收者为 this。
4. CGO：默认 CGO_ENABLED=0；依赖以标准库 + 必要纯 Go 第三方为主（见 go.mod）。

测试

$env:CGO_ENABLED=0
go test ./...

# 按包示例
go test ./gpu/wgsl/
go test ./gpu/internal/d3d12/    # Windows
go test ./system/window/

GPU 后端与平台相关测试以 gpu/README.md 为准。

许可证

MIT — Copyright 2026 liuqi0826