From f5a34f8adceaa26b9f563d3b08a47276d18fb96e Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Thu, 26 Mar 2026 01:50:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=20API=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=20-=20components=20=E5=92=8C=20scene=20=E6=A8=A1?= =?UTF-8?q?=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - components: 修复英文标题为中文，添加缺失组件文档 - 新增 camera-component, light-component, audio-source-component, audio-listener-component 类总览 - 修复 get-position.md 格式 - 更新 components.md 模块总览 - scene: 修复方法文档格式，新增缺失方法 - 修复 find.md, create-game-object.md 英文标题 - 新增 FindByID, SerializeToString, DeserializeFromString 方法文档 - 更新 scene.md 类总览方法列表 --- .../windows-audio-backend.md | 69 ++++++++++ .../audio-listener-component.md | 86 +++++++++++++ .../audio-source-component.md | 121 ++++++++++++++++++ .../camera-component/camera-component.md | 80 ++++++++++++ docs/api/components/component/component.md | 4 +- docs/api/components/component/get-scene.md | 2 +- docs/api/components/component/transform.md | 2 +- docs/api/components/components.md | 14 ++ .../components/game-object/add-component.md | 2 +- .../api/components/game-object/game-object.md | 6 +- docs/api/components/game-object/get-scene.md | 2 +- .../components/game-object/get-transform.md | 2 +- .../light-component/light-component.md | 90 +++++++++++++ .../transform-component/get-position.md | 35 ++--- .../transform-component.md | 4 +- docs/api/main.md | 4 +- docs/api/math/aabb/aabb.md | 61 +++++---- docs/api/math/bounds/bounds.md | 6 +- docs/api/math/box/box.md | 8 +- docs/api/math/color/color.md | 4 +- docs/api/math/frustum/frustum.md | 2 +- docs/api/math/math.md | 11 +- docs/api/math/matrix3/matrix3.md | 6 +- docs/api/math/matrix4/matrix4.md | 8 +- docs/api/math/plane/plane.md | 8 +- docs/api/math/quaternion/quaternion.md | 8 +- docs/api/math/ray/ray.md | 8 +- docs/api/math/rect/rect.md | 6 +- docs/api/math/sphere/sphere.md | 6 +- docs/api/math/transform/transform.md | 8 +- docs/api/math/vector2/vector2.md | 4 +- docs/api/math/vector3/vector3.md | 4 +- docs/api/math/vector4/vector4.md | 6 +- docs/api/math/viewport/viewport.md | 2 +- .../api/memory/proxy-allocator/constructor.md | 39 ++++++ docs/api/resources/audio-loader/index.md | 2 +- docs/api/resources/resources.md | 2 +- docs/api/resources/texture-loader/index.md | 10 +- docs/api/scene/scene-manager/scene-manager.md | 2 +- docs/api/scene/scene/create-game-object.md | 36 +++--- .../scene/scene/deserialize-from-string.md | 40 ++++++ docs/api/scene/scene/find-by-id.md | 36 ++++++ docs/api/scene/scene/find.md | 36 +++--- docs/api/scene/scene/scene.md | 11 +- docs/api/scene/scene/serialize-to-string.md | 33 +++++ docs/api/threading/task-system/task-system.md | 2 - 46 files changed, 781 insertions(+), 157 deletions(-) create mode 100644 docs/api/audio/windows-audio-backend/windows-audio-backend.md create mode 100644 docs/api/components/audio-listener-component/audio-listener-component.md create mode 100644 docs/api/components/audio-source-component/audio-source-component.md create mode 100644 docs/api/components/camera-component/camera-component.md create mode 100644 docs/api/components/light-component/light-component.md create mode 100644 docs/api/memory/proxy-allocator/constructor.md create mode 100644 docs/api/scene/scene/deserialize-from-string.md create mode 100644 docs/api/scene/scene/find-by-id.md create mode 100644 docs/api/scene/scene/serialize-to-string.md diff --git a/docs/api/audio/windows-audio-backend/windows-audio-backend.md b/docs/api/audio/windows-audio-backend/windows-audio-backend.md new file mode 100644 index 00000000..991d9129 --- /dev/null +++ b/docs/api/audio/windows-audio-backend/windows-audio-backend.md @@ -0,0 +1,69 @@ +# WindowsAudioBackend + +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `class` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +**描述**: Windows 平台音频后端实现，使用 Windows MultiMedia API (waveXxx 函数)。 + +## 概述 + +WindowsAudioBackend 是基于 Windows MultiMedia API 的音频后端实现，通过 waveXxx 函数提供音频输出能力。它运行在单独的音频线程上，使用双缓冲区交换机制实现流畅的音频播放，支持设备枚举、音量控制和静音管理。 + +该后端与 WASAPIBackend 类似，但使用更底层的 waveOut API 而非 WASAPI COM 接口，具有更好的兼容性和更低的依赖要求。 + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| `WindowsAudioBackend` | 构造函数 | +| `~WindowsAudioBackend` | 析构函数，关闭音频设备并清理资源 | +| `Initialize` | 初始化音频后端和设备 | +| `Shutdown` | 关闭音频后端并释放资源 | +| `GetDeviceName` | 获取当前音频设备名称 | +| `GetAvailableDevices` | 获取系统可用音频设备列表 | +| `SetDevice` | 设置音频输出设备 | +| `GetMasterVolume` | 获取主音量（0.0-1.0） | +| `SetMasterVolume` | 设置主音量（0.0-1.0） | +| `IsMuted` | 检查静音状态 | +| `SetMuted` | 设置静音状态 | +| `Start` | 启动音频处理线程 | +| `Stop` | 停止音频处理线程 | +| `Suspend` | 暂停音频处理 | +| `Resume` | 恢复音频处理 | +| `ProcessAudio` | 处理音频数据到输出缓冲区 | +| `IsRunning` | 检查音频线程是否正在运行 | +| `GetConfig` | 获取当前音频配置 | + +## 使用示例 + +```cpp +#include +#include + +using namespace XCEngine::Audio; + +void SetupAudioWithWindowsBackend() { + // 创建 Windows 音频后端 + auto backend = std::make_unique(); + + // 设置到音频系统 + AudioSystem::Get().SetBackend(std::move(backend)); + + // 初始化配置 + AudioConfig config; + config.sampleRate = 48000; + config.channels = 2; + config.bufferSize = 512; + + AudioSystem::Get().Initialize(config); +} +``` + +## 相关文档 + +- [Audio 模块总览](../audio.md) - Audio 模块总览 +- [IAudioBackend](../i-audio-backend/i-audio-backend.md) - 音频后端接口 +- [WASAPIBackend](../wasapi-backend/wasapi-backend.md) - WASAPI 后端实现 diff --git a/docs/api/components/audio-listener-component/audio-listener-component.md b/docs/api/components/audio-listener-component/audio-listener-component.md new file mode 100644 index 00000000..26167204 --- /dev/null +++ b/docs/api/components/audio-listener-component/audio-listener-component.md @@ -0,0 +1,86 @@ +# AudioListenerComponent + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +**描述**: 音频监听组件，接收声音并处理多普勒效应、混响和音量控制。 + +## 概述 + +AudioListenerComponent 是 XCEngine ECS 系统中的音频监听组件，通常附加到相机或玩家对象上。它负责接收场景中所有 AudioSourceComponent 发出的声音，并进行多普勒效应、混响和音量控制处理。每个场景通常只有一个 AudioListenerComponent。 + +## 公共方法 + +### 音量控制 + +| 方法 | 描述 | +|------|------| +| [`SetMasterVolume`](../../audio/audio-system/set-master-volume.md) | 设置主音量 | +| [`GetMasterVolume`](../../audio/audio-system/get-master-volume.md) | 获取主音量 | + +### 静音控制 + +| 方法 | 描述 | +|------|------| +| [`SetMute`](../../audio/audio-mixer/set-mute.md) | 设置静音状态 | +| [`IsMute`](is-mute.md) | 检查是否静音 | + +### 多普勒效应 + +| 方法 | 描述 | +|------|------| +| [`SetDopplerLevel`](set-doppler-level.md) | 设置多普勒效应等级 | +| [`GetDopplerLevel`](get-doppler-level.md) | 获取多普勒效应等级 | +| [`SetSpeedOfSound`](set-speed-of-sound.md) | 设置声速（米/秒） | +| [`GetSpeedOfSound`](get-speed-of-sound.md) | 获取声速 | + +### 混响 + +| 方法 | 描述 | +|------|------| +| [`SetReverbLevel`](set-reverb-level.md) | 设置混响等级 | +| [`GetReverbLevel`](get-reverb-level.md) | 获取混响等级 | +| [`SetReverb`](set-reverb.md) | 设置混响效果器 | +| [`GetReverb`](get-reverb.md) | 获取混响效果器 | + +### 频谱分析 + +| 方法 | 描述 | +|------|------| +| [`GetEnergy`](get-energy.md) | 获取当前能量值 | +| [`GetFrequencyData`](get-frequency-data.md) | 获取频谱数据 | +| [`GetFrequencyDataSize`](get-frequency-data-size.md) | 获取频谱数据大小 | + +## 使用示例 + +```cpp +#include +#include + +using namespace XCEngine::Components; + +void SetupAudioListener(GameObject* listenerObject) { + auto listener = listenerObject->AddComponent(); + + listener->SetMasterVolume(1.0f); + listener->SetDopplerLevel(1.0f); + listener->SetSpeedOfSound(343.0f); + listener->SetReverbLevel(0.5f); +} + +void AdjustVolume(GameObject* listenerObject, float volume) { + auto listener = listenerObject->GetComponent(); + if (listener) { + listener->SetMasterVolume(volume); + } +} +``` + +## 相关文档 + +- [Components 模块总览](../components.md) - Components 模块总览 +- [Component](../component/component.md) - 组件基类 +- [AudioSourceComponent](../audio-source-component/audio-source-component.md) - 音频源组件 diff --git a/docs/api/components/audio-source-component/audio-source-component.md b/docs/api/components/audio-source-component/audio-source-component.md new file mode 100644 index 00000000..329f4ec1 --- /dev/null +++ b/docs/api/components/audio-source-component/audio-source-component.md @@ -0,0 +1,121 @@ +# AudioSourceComponent + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +**描述**: 音频源组件，负责声音播放、3D 空间化、衰减和多普勒效应。 + +## 概述 + +AudioSourceComponent 是 XCEngine ECS 系统中的音频源组件，用于在场景中播放声音。它支持 3D 空间化、声音衰减、多普勒效应、混响区域混合等功能。该组件需要配合 AudioListenerComponent 使用来接收声音并进行音频处理。 + +## 公共方法 + +### 播放控制 + +| 方法 | 描述 | +|------|------| +| [`Play`](play.md) | 开始播放音频 | +| [`Pause`](pause.md) | 暂停播放 | +| [`Stop`](stop.md) | 停止播放 | +| [`IsPlaying`](is-playing.md) | 检查是否正在播放 | +| [`IsPaused`](is-paused.md) | 检查是否已暂停 | + +### 音频剪辑 + +| 方法 | 描述 | +|------|------| +| [`SetClip`](set-clip.md) | 设置音频剪辑 | +| [`GetClip`](get-clip.md) | 获取当前音频剪辑 | + +### 音频属性 + +| 方法 | 描述 | +|------|------| +| [`SetVolume`](../../audio/audio-mixer/set-volume.md) | 设置音量 | +| [`GetVolume`](get-volume.md) | 获取音量 | +| [`SetPitch`](set-pitch.md) | 设置音调 | +| [`GetPitch`](get-pitch.md) | 获取音调 | +| [`SetPan`](set-pan.md) | 设置平移 | +| [`GetPan`](get-pan.md) | 获取平移 | +| [`SetLooping`](set-looping.md) | 设置循环播放 | +| [`IsLooping`](is-looping.md) | 检查是否循环播放 | + +### 3D 空间化 + +| 方法 | 描述 | +|------|------| +| [`SetSpatialize`](set-spatialize.md) | 设置是否启用 3D 空间化 | +| [`IsSpatialize`](is-spatialize.md) | 检查是否启用 3D 空间化 | +| [`Set3DParams`](../../audio/audio-mixer/set-3d-params.md) | 设置 3D 音频参数 | +| [`Get3DParams`](get-3d-params.md) | 获取 3D 音频参数 | +| [`SetDopplerLevel`](set-doppler-level.md) | 设置多普勒效应等级 | +| [`GetDopplerLevel`](get-doppler-level.md) | 获取多普勒效应等级 | +| [`SetSpread`](set-spread.md) | 设置扩散角度 | +| [`GetSpread`](get-spread.md) | 获取扩散角度 | +| [`SetReverbZoneMix`](set-reverb-zone-mix.md) | 设置混响区域混合 | +| [`GetReverbZoneMix`](get-reverb-zone-mix.md) | 获取混响区域混合 | + +### 输出混音器 + +| 方法 | 描述 | +|------|------| +| [`SetOutputMixer`](../../audio/audio-mixer/set-output-mixer.md) | 设置输出混音器 | +| [`GetOutputMixer`](get-output-mixer.md) | 获取输出混音器 | + +### 播放时间 + +| 方法 | 描述 | +|------|------| +| [`SetTime`](set-time.md) | 设置播放位置 | +| [`GetTime`](get-time.md) | 获取当前播放位置 | +| [`GetDuration`](../../resources/audioclip/get-duration.md) | 获取音频总时长 | + +### 能量检测 + +| 方法 | 描述 | +|------|------| +| [`GetEnergy`](get-energy.md) | 获取当前能量值 | +| [`StartEnergyDetect`](start-energy-detect.md) | 开始能量检测 | +| [`StopEnergyDetect`](stop-energy-detect.md) | 停止能量检测 | +| [`IsEnergyDetecting`](is-energy-detecting.md) | 检查是否正在能量检测 | + +## 使用示例 + +```cpp +#include +#include +#include + +using namespace XCEngine::Components; + +void PlaySound(GameObject* audioObject) { + auto audioSource = audioObject->AddComponent(); + + audioSource->SetVolume(0.8f); + audioSource->SetPitch(1.0f); + audioSource->SetLooping(false); + audioSource->SetSpatialize(true); + + audioSource->Play(); +} + +void Setup3DAudio(GameObject* audioObject) { + auto audioSource = audioObject->AddComponent(); + + Audio::Audio3DParams params; + params.dopplerLevel = 1.0f; + params.spread = 0.0f; + params.reverbZoneMix = 1.0f; + audioSource->Set3DParams(params); +} +``` + +## 相关文档 + +- [Components 模块总览](../components.md) - Components 模块总览 +- [Component](../component/component.md) - 组件基类 +- [AudioListenerComponent](../audio-listener-component/audio-listener-component.md) - 音频监听组件 diff --git a/docs/api/components/camera-component/camera-component.md b/docs/api/components/camera-component/camera-component.md new file mode 100644 index 00000000..83910e48 --- /dev/null +++ b/docs/api/components/camera-component/camera-component.md @@ -0,0 +1,80 @@ +# CameraComponent + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +**描述**: 相机组件，定义视图和投影参数，支持透视和正交两种投影模式。 + +## 概述 + +CameraComponent 是 XCEngine ECS 系统中的相机组件，用于定义场景的观察视角。它支持透视投影（Perspective）和正交投影（Orthographic）两种模式，可以设置视场角、近裁剪面、远裁剪面、深度值和清除颜色等参数。 + +## 枚举 + +### CameraProjectionType + +| 枚举值 | 描述 | +|--------|------| +| `Perspective` | 透视投影，符合人眼观察习惯 | +| `Orthographic` | 正交投影，保持物体真实大小 | + +## 公共方法 + +### 投影设置 + +| 方法 | 描述 | +|------|------| +| [`GetProjectionType`](get-projection-type.md) | 获取投影类型 | +| [`SetProjectionType`](set-projection-type.md) | 设置投影类型 | +| [`GetFieldOfView`](get-field-of-view.md) | 获取视场角（透视投影） | +| [`SetFieldOfView`](set-field-of-view.md) | 设置视场角 | +| [`GetOrthographicSize`](get-orthographic-size.md) | 获取正交投影大小 | +| [`SetOrthographicSize`](set-orthographic-size.md) | 设置正交投影大小 | + +### 裁剪平面 + +| 方法 | 描述 | +|------|------| +| [`GetNearClipPlane`](get-near-clip-plane.md) | 获取近裁剪面距离 | +| [`SetNearClipPlane`](set-near-clip-plane.md) | 设置近裁剪面距离 | +| [`GetFarClipPlane`](get-far-clip-plane.md) | 获取远裁剪面距离 | +| [`SetFarClipPlane`](set-far-clip-plane.md) | 设置远裁剪面距离 | + +### 相机属性 + +| 方法 | 描述 | +|------|------| +| [`GetDepth`](../../rhi/texture/get-depth.md) | 获取深度值 | +| [`SetDepth`](set-depth.md) | 设置深度值 | +| [`IsPrimary`](is-primary.md) | 检查是否为主相机 | +| [`SetPrimary`](set-primary.md) | 设置为主相机 | +| [`GetClearColor`](get-clear-color.md) | 获取清除颜色 | +| [`SetClearColor`](../../rhi/opengl/pipeline-state/set-clear-color.md) | 设置清除颜色 | + +## 使用示例 + +```cpp +#include +#include + +using namespace XCEngine::Components; + +void SetupCamera(GameObject* cameraObject) { + auto camera = cameraObject->AddComponent(); + + camera->SetProjectionType(CameraProjectionType::Perspective); + camera->SetFieldOfView(60.0f); + camera->SetNearClipPlane(0.1f); + camera->SetFarClipPlane(1000.0f); + camera->SetPrimary(true); +} +``` + +## 相关文档 + +- [Components 模块总览](../components.md) - Components 模块总览 +- [Component](../component/component.md) - 组件基类 +- [TransformComponent](../transform-component/transform-component.md) - 变换组件 diff --git a/docs/api/components/component/component.md b/docs/api/components/component/component.md index 8ea4175c..9005c669 100644 --- a/docs/api/components/component/component.md +++ b/docs/api/components/component/component.md @@ -63,5 +63,5 @@ public: ## 相关文档 - [Components 模块总览](../components.md) - Components 模块总览 -- [GameObject](game-object/game-object.md) - 游戏对象 -- [TransformComponent](transform-component/transform-component.md) - 变换组件 +- [GameObject](../game-object/game-object.md) - 游戏对象 +- [TransformComponent](../transform-component/transform-component.md) - 变换组件 diff --git a/docs/api/components/component/get-scene.md b/docs/api/components/component/get-scene.md index 2ea02c23..d9b9c469 100644 --- a/docs/api/components/component/get-scene.md +++ b/docs/api/components/component/get-scene.md @@ -11,4 +11,4 @@ Scene* GetScene() const; ## 相关文档 - [Component 总览](component.md) -- [Scene](../scene/scene/scene.md) +- [Scene](../../scene/scene.md) diff --git a/docs/api/components/component/transform.md b/docs/api/components/component/transform.md index cf7e7664..77c1a4f8 100644 --- a/docs/api/components/component/transform.md +++ b/docs/api/components/component/transform.md @@ -13,4 +13,4 @@ TransformComponent& transform() const; ## 相关文档 - [Component 总览](component.md) -- [TransformComponent](transform-component/transform-component.md) +- [TransformComponent](../transform-component/transform-component.md) diff --git a/docs/api/components/components.md b/docs/api/components/components.md index 6b7f0e8f..eed43963 100644 --- a/docs/api/components/components.md +++ b/docs/api/components/components.md @@ -25,6 +25,20 @@ Components 模块是 XCEngine ECS 架构中的组件层，提供各种游戏对 |------|------|------| | [TransformComponent](transform-component/transform-component.md) | `TransformComponent.h` | 变换组件，包含位置、旋转、缩放 | +### 渲染组件 + +| 组件 | 文件 | 描述 | +|------|------|------| +| [CameraComponent](camera-component/camera-component.md) | `CameraComponent.h` | 相机组件，定义视图和投影参数 | +| [LightComponent](light-component/light-component.md) | `LightComponent.h` | 光源组件，支持方向光、点光、聚光灯 | + +### 音频组件 + +| 组件 | 文件 | 描述 | +|------|------|------| +| [AudioSourceComponent](audio-source-component/audio-source-component.md) | `AudioSourceComponent.h` | 音频源组件，负责声音播放和3D音效 | +| [AudioListenerComponent](audio-listener-component/audio-listener-component.md) | `AudioListenerComponent.h` | 音频监听组件，接收声音并处理多普勒效应和混响 | + ## 使用示例 ```cpp diff --git a/docs/api/components/game-object/add-component.md b/docs/api/components/game-object/add-component.md index 23af5776..29f357fa 100644 --- a/docs/api/components/game-object/add-component.md +++ b/docs/api/components/game-object/add-component.md @@ -20,4 +20,4 @@ T* AddComponent(Args&&... args); ## 相关文档 - [GameObject 总览](game-object.md) -- [Component](component/component.md) +- [Component](../component/component.md) diff --git a/docs/api/components/game-object/game-object.md b/docs/api/components/game-object/game-object.md index 01b48f88..54e263b5 100644 --- a/docs/api/components/game-object/game-object.md +++ b/docs/api/components/game-object/game-object.md @@ -113,6 +113,6 @@ void FindAndOperate() { ## 相关文档 - [Components 模块总览](../components.md) - Components 模块总览 -- [Component](component/component.md) - 组件基类 -- [TransformComponent](transform-component/transform-component.md) - 变换组件 -- [Scene](../scene/scene/scene.md) - 场景 +- [Component](../component/component.md) - 组件基类 +- [TransformComponent](../transform-component/transform-component.md) - 变换组件 +- [Scene](../../scene/scene.md) - 场景 diff --git a/docs/api/components/game-object/get-scene.md b/docs/api/components/game-object/get-scene.md index 766a6a1b..a7aa7ea1 100644 --- a/docs/api/components/game-object/get-scene.md +++ b/docs/api/components/game-object/get-scene.md @@ -11,4 +11,4 @@ Scene* GetScene() const; ## 相关文档 - [GameObject 总览](game-object.md) -- [Scene](../scene/scene/scene.md) +- [Scene](../../scene/scene.md) diff --git a/docs/api/components/game-object/get-transform.md b/docs/api/components/game-object/get-transform.md index ed30aa95..cbbd8dc2 100644 --- a/docs/api/components/game-object/get-transform.md +++ b/docs/api/components/game-object/get-transform.md @@ -12,4 +12,4 @@ const TransformComponent* GetTransform() const; ## 相关文档 - [GameObject 总览](game-object.md) -- [TransformComponent](transform-component/transform-component.md) +- [TransformComponent](../transform-component/transform-component.md) diff --git a/docs/api/components/light-component/light-component.md b/docs/api/components/light-component/light-component.md new file mode 100644 index 00000000..093f0d8f --- /dev/null +++ b/docs/api/components/light-component/light-component.md @@ -0,0 +1,90 @@ +# LightComponent + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Components/LightComponent.h` + +**描述**: 光源组件，支持方向光、点光、聚光灯三种类型，可设置颜色、强度和阴影。 + +## 概述 + +LightComponent 是 XCEngine ECS 系统中的光源组件，支持三种光源类型：方向光（Directional）、点光（Point）和聚光灯（Spot）。方向光从无穷远处照射，模拟太阳光；点光从一个点向所有方向照射；聚光灯沿一个锥形方向照射。光源组件可以设置颜色、强度、作用范围和是否投射阴影。 + +## 枚举 + +### LightType + +| 枚举值 | 描述 | +|--------|------| +| `Directional` | 方向光，从无穷远处照射 | +| `Point` | 点光，从一个点向所有方向照射 | +| `Spot` | 聚光灯，沿锥形方向照射 | + +## 公共方法 + +### 光源类型 + +| 方法 | 描述 | +|------|------| +| [`GetLightType`](get-light-type.md) | 获取光源类型 | +| [`SetLightType`](set-light-type.md) | 设置光源类型 | + +### 光源属性 + +| 方法 | 描述 | +|------|------| +| [`GetColor`](get-color.md) | 获取光源颜色 | +| [`SetColor`](set-color.md) | 设置光源颜色 | +| [`GetIntensity`](get-intensity.md) | 获取光源强度 | +| [`SetIntensity`](set-intensity.md) | 设置光源强度 | +| [`GetRange`](get-range.md) | 获取作用范围（点光/聚光灯） | +| [`SetRange`](set-range.md) | 设置作用范围 | + +### 聚光灯属性 + +| 方法 | 描述 | +|------|------| +| [`GetSpotAngle`](get-spot-angle.md) | 获取聚光灯角度 | +| [`SetSpotAngle`](set-spot-angle.md) | 设置聚光灯角度 | + +### 阴影 + +| 方法 | 描述 | +|------|------| +| [`GetCastsShadows`](get-casts-shadows.md) | 检查是否投射阴影 | +| [`SetCastsShadows`](set-casts-shadows.md) | 设置是否投射阴影 | + +## 使用示例 + +```cpp +#include +#include + +using namespace XCEngine::Components; + +void SetupLighting(GameObject* lightObject) { + auto light = lightObject->AddComponent(); + + light->SetLightType(LightType::Directional); + light->SetColor(Math::Color::White()); + light->SetIntensity(1.0f); + light->SetCastsShadows(true); +} + +void SetupPointLight(GameObject* pointLightObject) { + auto pointLight = pointLightObject->AddComponent(); + + pointLight->SetLightType(LightType::Point); + pointLight->SetColor(Math::Color(1.0f, 0.8f, 0.6f, 1.0f)); + pointLight->SetIntensity(2.0f); + pointLight->SetRange(10.0f); +} +``` + +## 相关文档 + +- [Components 模块总览](../components.md) - Components 模块总览 +- [Component](../component/component.md) - 组件基类 +- [TransformComponent](../transform-component/transform-component.md) - 变换组件 diff --git a/docs/api/components/transform-component/get-position.md b/docs/api/components/transform-component/get-position.md index 171673c8..413d8a78 100644 --- a/docs/api/components/transform-component/get-position.md +++ b/docs/api/components/transform-component/get-position.md @@ -1,33 +1,34 @@ -# GetPosition +# TransformComponent::GetPosition -Get the world position of this transform. - -## Syntax +获取变换的世界空间位置。 ```cpp Math::Vector3 GetPosition() const; ``` -## Returns +返回变换的世界空间位置。如果变换有父对象，世界位置由局部位置与父对象世界位置组合计算得出。 -Returns the world position as a `Math::Vector3`. +**返回：** `Math::Vector3` - 世界空间位置向量 -## Remarks +**线程安全：** ✅ (只读操作) -Returns the world-space position of this transform. If this transform has a parent, the world position is computed by combining the local position with the parent's world position. - -## See Also - -- [GetLocalPosition](get-local-position) -- [SetLocalPosition](set-local-position) -- [SetPosition](set-position) - -## Examples +**示例：** ```cpp +#include + +using namespace XCEngine::Components; + void Example(TransformComponent* transform) { Math::Vector3 worldPos = transform->GetPosition(); - XC_LOG_INFO("World position: ({}, {}, {})", + printf("World position: (%f, %f, %f)\n", worldPos.x, worldPos.y, worldPos.z); } ``` + +## 相关文档 + +- [TransformComponent 总览](transform-component.md) - 返回类总览 +- [GetLocalPosition](get-local-position.md) - 获取局部位置 +- [SetPosition](set-position.md) - 设置世界位置 +- [SetLocalPosition](set-local-position.md) - 设置局部位置 diff --git a/docs/api/components/transform-component/transform-component.md b/docs/api/components/transform-component/transform-component.md index d28801f9..c5cae7c7 100644 --- a/docs/api/components/transform-component/transform-component.md +++ b/docs/api/components/transform-component/transform-component.md @@ -122,5 +122,5 @@ void TransformExample(TransformComponent* transform) { ## 相关文档 - [Components 模块总览](../components.md) - Components 模块总览 -- [Component](component/component.md) - 组件基类 -- [GameObject](game-object/game-object.md) - 游戏对象 +- [Component](../component/component.md) - 组件基类 +- [GameObject](../game-object/game-object.md) - 游戏对象 diff --git a/docs/api/main.md b/docs/api/main.md index 46bb6257..3513fe85 100644 --- a/docs/api/main.md +++ b/docs/api/main.md @@ -9,8 +9,8 @@ | 模块 | 文档目录 | 描述 | |------|----------|------| | **RHI** | [rhi/](rhi/rhi.md) | 渲染硬件接口抽象层 | -| **D3D12** | [rhi/d3d12/](rhi/opengl/overview.md) | DirectX 12 后端实现 | -| **OpenGL** | [rhi/opengl/](rhi/opengl/overview.md) | OpenGL 后端实现 | +| **D3D12** | [rhi/d3d12/](rhi/d3d12/d3d12.md) | DirectX 12 后端实现 | +| **OpenGL** | [rhi/opengl/](rhi/opengl/opengl.md) | OpenGL 后端实现 | | **Containers** | [containers/](containers/containers.md) | 容器数据结构 | | **Memory** | [memory/](memory/memory.md) | 内存管理 | | **Threading** | [threading/](threading/threading.md) | 多线程和任务系统 | diff --git a/docs/api/math/aabb/aabb.md b/docs/api/math/aabb/aabb.md index 77cf58db..9db1e18a 100644 --- a/docs/api/math/aabb/aabb.md +++ b/docs/api/math/aabb/aabb.md @@ -1,47 +1,62 @@ -# AABB / OBB +# OBB **命名空间**: `XCEngine::Math` **类型**: `struct` -**头文件**: `XCEngine/Math/AABB.h` +**头文件**: `XCEngine/Core/Math/AABB.h` -**描述**: 轴对齐包围盒 (AABB) 和有向包围盒 (OBB) +**描述**: 有向包围盒（Oriented Bounding Box），支持任意方向旋转的盒状包围体 ## 概述 -`AABB` 在 Math 库中通过 `Bounds` 类型实现。OBB 是可以任意方向旋转的包围盒。 +OBB（Oriented Bounding Box）是一种包围盒类型，与轴对齐包围盒（AABB）不同，OBB 可以任意旋转，因此能够更紧凑地包围复杂形状的对象。OBB 由一个中心点、半长向量（extents）和一个变换矩阵组成，变换矩阵定义了盒子的朝向。 -## AABB - -`AABB` 在 Math 库中通过 `Bounds` 类型实现，参见 [./bounds/bounds.md](../bounds/bounds.md)。 - -## OBB - 有向包围盒 - -OBB 是可以任意方向旋转的包围盒。 +OBB 常用于碰撞检测、剔除运算和物理模拟等场景。 ## 结构体成员 | 成员 | 类型 | 描述 | |------|------|------| | `center` | `Vector3` | OBB 中心点 | -| `extents` | `Vector3` | 从中心到每个面的距离 | -| `transform` | `Matrix4` | 变换矩阵 | +| `extents` | `Vector3` | 从中心到每个面的距离（半长） | +| `transform` | `Matrix4x4` | 变换矩阵，定义盒子朝向 | ## 公共方法 | 方法 | 描述 | |------|------| -| `OBB()` | 默认构造 | -| `OBB(const Vector3& center, const Vector3& extents)` | 从中心和半长构造 | -| [GetAxis](obb-getaxis.md) | 获取局部轴 | -| [GetMin](obb-getmin.md) | 局部空间最小点 | -| [GetMax](obb-getmax.md) | 局部空间最大点 | -| [Contains](obb-contains.md) | 点是否在 OBB 内 | -| [Intersects(OBB)](intersects-obb.md) | 与另一个 OBB 相交 | -| [Intersects(Sphere)](intersects-sphere.md) | 与球体相交 | +| `GetAxis(int index)` | 获取指定索引处的局部轴方向 | +| `GetMin()` | 获取局部空间最小顶点 | +| `GetMax()` | 获取局部空间最大顶点 | +| `Contains(const Vector3& point)` | 检测点是否在 OBB 内 | +| `Intersects(const OBB& other)` | 检测与另一个 OBB 是否相交 | +| `Intersects(const Sphere& sphere)` | 检测与球体是否相交 | + +## 使用示例 + +```cpp +#include +#include +#include + +using namespace XCEngine::Math; + +OBB obb(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.5f, 1.0f)); + +Vector3 point(0.5f, 0.25f, 0.5f); +if (obb.Contains(point)) { + // 点在 OBB 内 +} + +Vector3 axis = obb.GetAxis(0); +Vector3 min = obb.GetMin(); +Vector3 max = obb.GetMax(); +``` ## 相关文档 -- [Bounds](../bounds/bounds.md) - 轴对齐包围盒 -- [Math 模块总览](../math.md) \ No newline at end of file +- [Bounds](bounds/bounds.md) - 轴对齐包围盒 +- [Vector3](vector3/vector3.md) - 三维向量 +- [Matrix4](matrix4/matrix4.md) - 4x4 变换矩阵 +- [Sphere](sphere/sphere.md) - 球体 diff --git a/docs/api/math/bounds/bounds.md b/docs/api/math/bounds/bounds.md index 9886a87f..50641898 100644 --- a/docs/api/math/bounds/bounds.md +++ b/docs/api/math/bounds/bounds.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Bounds.h` +**头文件**: `XCEngine/Core/Math/Bounds.h` **描述**: 轴对齐包围盒，用于场景管理中的快速剔除 @@ -37,8 +37,8 @@ Bounds 表示一个轴对齐包围盒（AABB），使用中心点 `center` 和 ## 使用示例 ```cpp -#include -#include +#include +#include using namespace XCEngine::Math; diff --git a/docs/api/math/box/box.md b/docs/api/math/box/box.md index 0a6418ff..1992c792 100644 --- a/docs/api/math/box/box.md +++ b/docs/api/math/box/box.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Box.h` +**头文件**: `XCEngine/Core/Math/Box.h` **描述**: 轴对齐盒体，用于碰撞检测和视锥体裁剪 @@ -41,9 +41,9 @@ ## 使用示例 ```cpp -#include -#include -#include +#include +#include +#include using namespace XCEngine::Math; diff --git a/docs/api/math/color/color.md b/docs/api/math/color/color.md index 6add2287..f28481d4 100644 --- a/docs/api/math/color/color.md +++ b/docs/api/math/color/color.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Color.h` +**头文件**: `XCEngine/Core/Math/Color.h` **描述**: 颜色结构体，支持 RGBA 浮点分量，用于图形渲染 @@ -79,7 +79,7 @@ Color halfAlpha(0.5f, 0.5f, 0.5f); // a = 1.0f ## 使用示例 ```cpp -#include +#include using namespace XCEngine::Math; diff --git a/docs/api/math/frustum/frustum.md b/docs/api/math/frustum/frustum.md index 514b226e..caf9a971 100644 --- a/docs/api/math/frustum/frustum.md +++ b/docs/api/math/frustum/frustum.md @@ -4,7 +4,7 @@ **类型**: `class` -**头文件**: `XCEngine/Math/Frustum.h` +**头文件**: `XCEngine/Core/Math/Frustum.h` **描述**: 视锥体，用于 3D 裁剪和可见性判断 diff --git a/docs/api/math/math.md b/docs/api/math/math.md index d4a205f7..d007fb1a 100644 --- a/docs/api/math/math.md +++ b/docs/api/math/math.md @@ -43,8 +43,7 @@ Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四 | [Plane](plane/plane.md) | `Plane.h` | 平面 | | [Sphere](sphere/sphere.md) | `Sphere.h` | 球体 | | [Box](box/box.md) | `Box.h` | 盒子 | -| [Bounds](bounds/bounds.md) | `Bounds.h` | 包围盒 | -| [AABB](aabb/aabb.md) | `AABB.h` | 轴对齐包围盒 | +| [Bounds](bounds/bounds.md) | `Bounds.h` | 轴对齐包围盒 | | [Frustum](frustum/frustum.md) | `Frustum.h` | 视锥体 | | [Rect](rect/rect.md) | `Rect.h` | 二维矩形 | @@ -72,10 +71,10 @@ Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四 ## 使用示例 ```cpp -#include -#include -#include -#include +#include +#include +#include +#include using namespace XCEngine::Math; diff --git a/docs/api/math/matrix3/matrix3.md b/docs/api/math/matrix3/matrix3.md index 6b1af9eb..206320be 100644 --- a/docs/api/math/matrix3/matrix3.md +++ b/docs/api/math/matrix3/matrix3.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Matrix3.h` +**头文件**: `XCEngine/Core/Math/Matrix3.h` **描述**: 3x3 矩阵，用于旋转变换和线性代数运算。 @@ -56,8 +56,8 @@ using Matrix3 = Matrix3x3; ## 使用示例 ```cpp -#include -#include +#include +#include using namespace XCEngine::Math; diff --git a/docs/api/math/matrix4/matrix4.md b/docs/api/math/matrix4/matrix4.md index ebb6c96a..ca035a25 100644 --- a/docs/api/math/matrix4/matrix4.md +++ b/docs/api/math/matrix4/matrix4.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Matrix4.h` +**头文件**: `XCEngine/Core/Math/Matrix4.h` **描述**: 4x4 矩阵，用于 3D 变换（平移、旋转、缩放）、视图和投影计算 @@ -49,9 +49,9 @@ ## 使用示例 ```cpp -#include "XCEngine/Math/Matrix4.h" -#include "XCEngine/Math/Vector3.h" -#include "XCEngine/Math/Quaternion.h" +#include "XCEngine/Core/Math/Matrix4.h" +#include "XCEngine/Core/Math/Vector3.h" +#include "XCEngine/Core/Math/Quaternion.h" using namespace XCEngine::Math; diff --git a/docs/api/math/plane/plane.md b/docs/api/math/plane/plane.md index 6d8ebb33..decabc3a 100644 --- a/docs/api/math/plane/plane.md +++ b/docs/api/math/plane/plane.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Plane.h` +**头文件**: `XCEngine/Core/Math/Plane.h` **描述**: 平面，用于 3D 空间中的平面表示和相交测试 @@ -36,9 +36,9 @@ ## 使用示例 ```cpp -#include -#include -#include +#include +#include +#include using namespace XCEngine::Math; diff --git a/docs/api/math/quaternion/quaternion.md b/docs/api/math/quaternion/quaternion.md index fe429444..001b1e1c 100644 --- a/docs/api/math/quaternion/quaternion.md +++ b/docs/api/math/quaternion/quaternion.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Quaternion.h` +**头文件**: `XCEngine/Core/Math/Quaternion.h` **描述**: 四元数，用于表示三维旋转 @@ -43,9 +43,9 @@ Quaternion 提供了一套完整的三维旋转表示和操作方法。四元数 ## 使用示例 ```cpp -#include -#include -#include +#include +#include +#include using namespace XCEngine::Math; diff --git a/docs/api/math/ray/ray.md b/docs/api/math/ray/ray.md index e114f5ec..6ca78386 100644 --- a/docs/api/math/ray/ray.md +++ b/docs/api/math/ray/ray.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Ray.h` +**头文件**: `XCEngine/Core/Math/Ray.h` **描述**: 射线，用于 3D 拾取和光线追踪 @@ -35,9 +35,9 @@ ## 使用示例 ```cpp -#include -#include -#include +#include +#include +#include using namespace XCEngine::Math; diff --git a/docs/api/math/rect/rect.md b/docs/api/math/rect/rect.md index 8f2665c7..7814c0b5 100644 --- a/docs/api/math/rect/rect.md +++ b/docs/api/math/rect/rect.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Rect.h` +**头文件**: `XCEngine/Core/Math/Rect.h` **描述**: 二维矩形，用于表示平面上的矩形区域 @@ -42,8 +42,8 @@ Rect 结构体表示一个二维矩形，由位置 `(x, y)` 和尺寸 `(width, h ## 使用示例 ```cpp -#include "XCEngine/Math/Rect.h" -#include "XCEngine/Math/Vector2.h" +#include "XCEngine/Core/Math/Rect.h" +#include "XCEngine/Core/Math/Vector2.h" #include using namespace XCEngine::Math; diff --git a/docs/api/math/sphere/sphere.md b/docs/api/math/sphere/sphere.md index 13af9c06..144b7470 100644 --- a/docs/api/math/sphere/sphere.md +++ b/docs/api/math/sphere/sphere.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Sphere.h` +**头文件**: `XCEngine/Core/Math/Sphere.h` **描述**: 球体，用于碰撞检测和范围查询 @@ -31,8 +31,8 @@ ## 使用示例 ```cpp -#include -#include +#include +#include using namespace XCEngine::Math; diff --git a/docs/api/math/transform/transform.md b/docs/api/math/transform/transform.md index 43bcd0d5..750e416d 100644 --- a/docs/api/math/transform/transform.md +++ b/docs/api/math/transform/transform.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Transform.h` +**头文件**: `XCEngine/Core/Math/Transform.h` **描述**: 变换组件，包含位置、旋转和缩放，用于层级变换计算 @@ -43,9 +43,9 @@ ## 使用示例 ```cpp -#include "XCEngine/Math/Transform.h" -#include "XCEngine/Math/Vector3.h" -#include "XCEngine/Math/Quaternion.h" +#include "XCEngine/Core/Math/Transform.h" +#include "XCEngine/Core/Math/Vector3.h" +#include "XCEngine/Core/Math/Quaternion.h" using namespace XCEngine::Math; diff --git a/docs/api/math/vector2/vector2.md b/docs/api/math/vector2/vector2.md index c3d6136a..20efb3a1 100644 --- a/docs/api/math/vector2/vector2.md +++ b/docs/api/math/vector2/vector2.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Vector2.h` +**头文件**: `XCEngine/Core/Math/Vector2.h` **描述**: 二维向量，支持 2D 游戏开发和图形计算 @@ -51,7 +51,7 @@ Vector2 是 XCEngine 中的二维向量结构体，用于表示 2D 空间中的 ## 使用示例 ```cpp -#include "XCEngine/Math/Vector2.h" +#include "XCEngine/Core/Math/Vector2.h" using namespace XCEngine::Math; diff --git a/docs/api/math/vector3/vector3.md b/docs/api/math/vector3/vector3.md index fbb3f3b5..1bfad8cf 100644 --- a/docs/api/math/vector3/vector3.md +++ b/docs/api/math/vector3/vector3.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Vector3.h` +**头文件**: `XCEngine/Core/Math/Vector3.h` **描述**: 三维向量，用于 3D 图形和游戏开发中的位置、方向和缩放计算 @@ -68,7 +68,7 @@ Vector3 是 XCEngine 中用于表示三维向量的核心类型，支持常见 ## 使用示例 ```cpp -#include "XCEngine/Math/Vector3.h" +#include "XCEngine/Core/Math/Vector3.h" #include using namespace XCEngine::Math; diff --git a/docs/api/math/vector4/vector4.md b/docs/api/math/vector4/vector4.md index 0fb5026e..70df5adc 100644 --- a/docs/api/math/vector4/vector4.md +++ b/docs/api/math/vector4/vector4.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Math/Vector4.h` +**头文件**: `XCEngine/Core/Math/Vector4.h` **描述**: 四维向量，用于齐次坐标变换和四元数相关计算 @@ -47,8 +47,8 @@ Vector4 是四维向量结构体，常用于： ## 使用示例 ```cpp -#include -#include +#include +#include #include int main() { diff --git a/docs/api/math/viewport/viewport.md b/docs/api/math/viewport/viewport.md index 0119bce6..12917763 100644 --- a/docs/api/math/viewport/viewport.md +++ b/docs/api/math/viewport/viewport.md @@ -2,7 +2,7 @@ 渲染视口结构体，用于屏幕到归一化坐标的映射。 -**头文件：** `#include ` +**头文件：** `#include ` **命名空间：** `XCEngine::Math` diff --git a/docs/api/memory/proxy-allocator/constructor.md b/docs/api/memory/proxy-allocator/constructor.md new file mode 100644 index 00000000..58848f6d --- /dev/null +++ b/docs/api/memory/proxy-allocator/constructor.md @@ -0,0 +1,39 @@ +# ProxyAllocator::ProxyAllocator + +```cpp +ProxyAllocator(IAllocator* underlying, const char* name); +``` + +构造一个代理分配器，包装底层分配器并记录分配统计。所有 `Allocate`、`Free`、`Reallocate` 调用都会被转发到底层分配器，同时记录统计信息。名称用于日志和报告。 + +**参数：** +- `underlying` - 被包装的底层分配器，不能为 `nullptr` +- `name` - 代理分配器的名称字符串 + +**返回：** 无 + +**复杂度：** O(1) + +**线程安全：** ✅ (内部使用 mutex 保护统计数据) + +**示例：** + +```cpp +#include +#include + +MemoryManager::Get().Initialize(); + +// 使用系统分配器作为底层 +IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator(); +ProxyAllocator proxy(sysAlloc, "TempAllocations"); + +// 通过代理分配 +void* ptr = proxy.Allocate(1024); +proxy.Free(ptr); +``` + +## 相关文档 + +- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览 +- [`~ProxyAllocator`](~proxy-allocator.md) - 析构函数 diff --git a/docs/api/resources/audio-loader/index.md b/docs/api/resources/audio-loader/index.md index 073f0a87..5b83851f 100644 --- a/docs/api/resources/audio-loader/index.md +++ b/docs/api/resources/audio-loader/index.md @@ -22,7 +22,7 @@ |------|--------|------| | [AudioLoader](constructor.md) | - | 构造函数 | | [~AudioLoader](destructor.md) | - | 析构函数 | -| [GetResourceType](get-resource-type.md) | `ResourceType` | 返回资源类型 `AudioClip` | +| [GetResourceType](../shader-loader/methods/get-resource-type.md) | `ResourceType` | 返回资源类型 `AudioClip` | | [GetSupportedExtensions](get-supported-extensions.md) | `Array` | 获取支持的扩展名列表 | | [CanLoad](can-load.md) | `bool` | 检查是否能够加载指定路径的资源 | | [Load](load.md) | `LoadResult` | 加载音频资源 | diff --git a/docs/api/resources/resources.md b/docs/api/resources/resources.md index e87bdb84..ec3f28c5 100644 --- a/docs/api/resources/resources.md +++ b/docs/api/resources/resources.md @@ -21,7 +21,7 @@ Resources 模块提供了一套完整的资源管理解决方案，支持同步 | [IResource](iresource/iresource.md) | `IResource.h` | 资源基类 | | [ResourceHandle](resourcehandle/resourcehandle.md) | `ResourceHandle.h` | 资源句柄模板 | | [IResourceLoader](iloader/iloader.md) | `IResourceLoader.h` | 资源加载器接口 | -| [ShaderLoader](shaderloader/index.md) | `ShaderLoader.h` | 着色器加载器 | +| [ShaderLoader](../rhi/d3d12/fence/index.md) | `ShaderLoader.h` | 着色器加载器 | | [ResourceManager](resourcemanager/resourcemanager.md) | `ResourceManager.h` | 资源管理器 | | [ResourceCache](resourcecache/resourcecache.md) | `ResourceCache.h` | 资源缓存 | | [AsyncLoader](asyncloader/asyncloader.md) | `AsyncLoader.h` | 异步加载器 | diff --git a/docs/api/resources/texture-loader/index.md b/docs/api/resources/texture-loader/index.md index 21712ac0..7395defc 100644 --- a/docs/api/resources/texture-loader/index.md +++ b/docs/api/resources/texture-loader/index.md @@ -36,11 +36,11 @@ |------|------| | [TextureLoader](constructor.md) | 构造函数 | | [~TextureLoader](destructor.md) | 析构函数 | -| [GetResourceType](get-resource-type.md) | 返回 `ResourceType::Texture` | -| [GetSupportedExtensions](get-supported-extensions.md) | 获取支持的扩展名列表 | -| [CanLoad](can-load.md) | 检查是否支持加载指定路径的纹理 | -| [Load](load.md) | 加载纹理资源 | -| [GetDefaultSettings](get-default-settings.md) | 获取默认导入设置 | +| [GetResourceType](../shader-loader/methods/get-resource-type.md) | 返回 `ResourceType::Texture` | +| [GetSupportedExtensions](../audio-loader/get-supported-extensions.md) | 获取支持的扩展名列表 | +| [CanLoad](../audio-loader/can-load.md) | 检查是否支持加载指定路径的纹理 | +| [Load](../../scene/scene/load.md) | 加载纹理资源 | +| [GetDefaultSettings](../audio-loader/get-default-settings.md) | 获取默认导入设置 | ### GetResourceType diff --git a/docs/api/scene/scene-manager/scene-manager.md b/docs/api/scene/scene-manager/scene-manager.md index 5692ffda..8dc7b410 100644 --- a/docs/api/scene/scene-manager/scene-manager.md +++ b/docs/api/scene/scene-manager/scene-manager.md @@ -71,4 +71,4 @@ void SceneManagerExample() { ## 相关文档 - [Scene 模块总览](../scene.md) - Scene 模块总览 -- [Scene](scene/scene.md) - 场景类 +- [Scene](../scene.md) - 场景类 diff --git a/docs/api/scene/scene/create-game-object.md b/docs/api/scene/scene/create-game-object.md index 037d7989..26d71790 100644 --- a/docs/api/scene/scene/create-game-object.md +++ b/docs/api/scene/scene/create-game-object.md @@ -1,35 +1,35 @@ -# CreateGameObject +# Scene::CreateGameObject -Create a new GameObject in this scene. - -## Syntax +在场景中创建新的 GameObject。 ```cpp GameObject* CreateGameObject(const std::string& name, GameObject* parent = nullptr); ``` -## Parameters +创建一个具有指定名称的新 GameObject，并可选择设置其父对象。GameObject 由场景拥有，当场景被销毁时也会被销毁。 -- `name` - The name of the new GameObject. -- `parent` - Optional parent GameObject (defaults to `nullptr`). +**参数：** +- `name` - 新 GameObject 的名称 +- `parent` - 可选的父 GameObject（默认为 `nullptr`） -## Returns +**返回：** `GameObject*` - 指向新创建的 GameObject 的指针 -Returns a pointer to the newly created `GameObject`. +**线程安全：** ❌ (非线程安全，应在主线程调用) -## Remarks - -Creates a new GameObject with the specified name and optionally sets its parent. The GameObject is owned by the scene and will be destroyed when the scene is destroyed. - -## See Also - -- [DestroyGameObject](destroy-game-object) - -## Examples +**示例：** ```cpp +#include + +using namespace XCEngine::Components; + void Example(Scene* scene) { GameObject* player = scene->CreateGameObject("Player"); GameObject* weapon = scene->CreateGameObject("Sword", player); } ``` + +## 相关文档 + +- [Scene 总览](scene.md) - 返回类总览 +- [DestroyGameObject](destroy-game-object.md) - 销毁 GameObject diff --git a/docs/api/scene/scene/deserialize-from-string.md b/docs/api/scene/scene/deserialize-from-string.md new file mode 100644 index 00000000..95387b9c --- /dev/null +++ b/docs/api/scene/scene/deserialize-from-string.md @@ -0,0 +1,40 @@ +# Scene::DeserializeFromString + +从字符串反序列化场景。 + +```cpp +void DeserializeFromString(const std::string& data); +``` + +从 JSON 格式的字符串数据恢复场景的完整状态，包括所有 GameObject、组件和层级结构。 + +**参数：** +- `data` - JSON 格式的序列化数据 + +**线程安全：** ❌ (非线程安全，应在主线程调用) + +**注意：** +- 此操作会清空当前场景的所有数据 +- 反序列化后的 GameObject 引用可能与原始引用不同 + +**示例：** + +```cpp +#include + +using namespace XCEngine::Components; + +void Example(Scene* scene) { + std::string data = R"({ + "name": "GameScene", + "gameObjects": [...] + })"; + scene->DeserializeFromString(data); +} +``` + +## 相关文档 + +- [Scene 总览](scene.md) - 返回类总览 +- [Save](save.md) - 保存到文件 +- [SerializeToString](serialize-to-string.md) - 序列化为字符串 diff --git a/docs/api/scene/scene/find-by-id.md b/docs/api/scene/scene/find-by-id.md new file mode 100644 index 00000000..48286dc0 --- /dev/null +++ b/docs/api/scene/scene/find-by-id.md @@ -0,0 +1,36 @@ +# Scene::FindByID + +按 ID 查找 GameObject。 + +```cpp +GameObject* FindByID(GameObjectID id) const; +``` + +通过游戏对象的唯一标识符查找 GameObject。 + +**参数：** +- `id` - GameObject 的唯一标识符 + +**返回：** `GameObject*` - 指向找到的 GameObject 的指针，未找到则返回 `nullptr` + +**线程安全：** ✅ (只读操作) + +**示例：** + +```cpp +#include + +using namespace XCEngine::Components; + +void Example(Scene* scene, GameObjectID id) { + GameObject* obj = scene->FindByID(id); + if (obj) { + printf("Found object: %s\n", obj->GetName().c_str()); + } +} +``` + +## 相关文档 + +- [Scene 总览](scene.md) - 返回类总览 +- [Find](find.md) - 按名称查找 diff --git a/docs/api/scene/scene/find.md b/docs/api/scene/scene/find.md index 4f6335fb..9535e248 100644 --- a/docs/api/scene/scene/find.md +++ b/docs/api/scene/scene/find.md @@ -1,36 +1,36 @@ -# Find +# Scene::Find -Find a GameObject by name. - -## Syntax +按名称查找 GameObject。 ```cpp GameObject* Find(const std::string& name) const; ``` -## Parameters +在场景中搜索具有指定名称的 GameObject。搜索包括所有根对象及其子对象。 -- `name` - The name of the GameObject to find. +**参数：** +- `name` - 要查找的 GameObject 名称 -## Returns +**返回：** `GameObject*` - 指向找到的 GameObject 的指针，未找到则返回 `nullptr` -Returns a pointer to the GameObject with the specified name, or `nullptr` if not found. +**线程安全：** ✅ (只读操作) -## Remarks - -Searches the scene for a GameObject with the specified name. The search includes all root GameObjects and their children. - -## See Also - -- [FindGameObjectWithTag](find-game-object-with-tag) - -## Examples +**示例：** ```cpp +#include + +using namespace XCEngine::Components; + void Example(Scene* scene) { GameObject* player = scene->Find("Player"); if (player) { - XC_LOG_INFO("Found player!"); + printf("Found player!\n"); } } ``` + +## 相关文档 + +- [Scene 总览](scene.md) - 返回类总览 +- [FindGameObjectWithTag](find-game-object-with-tag.md) - 按标签查找 diff --git a/docs/api/scene/scene/scene.md b/docs/api/scene/scene/scene.md index a2be9074..3e68e5c5 100644 --- a/docs/api/scene/scene/scene.md +++ b/docs/api/scene/scene/scene.md @@ -42,6 +42,7 @@ Scene 是 XCEngine 中的场景类，代表一个独立的游戏空间（如主 | 方法 | 描述 | |------|------| | [`Find`](find.md) | 按名称查找 GameObject | +| [`FindByID`](find-by-id.md) | 按 ID 查找 GameObject | | [`FindGameObjectWithTag`](find-game-object-with-tag.md) | 按标签查找 GameObject | | [`FindObjectOfType`](find-object-of-type.md) | 查找指定类型的组件 | | [`FindObjectsOfType`](find-objects-of-type.md) | 查找所有指定类型的组件 | @@ -54,8 +55,10 @@ Scene 是 XCEngine 中的场景类，代表一个独立的游戏空间（如主 | [`Update`](update.md) | 每帧更新场景 | | [`FixedUpdate`](fixed-update.md) | 固定频率更新 | | [`LateUpdate`](late-update.md) | 晚更新 | -| [`Load`](load.md) | 加载场景 | -| [`Save`](save.md) | 保存场景 | +| [`Load`](load.md) | 从文件加载场景 | +| [`Save`](save.md) | 保存场景到文件 | +| [`SerializeToString`](serialize-to-string.md) | 序列化为字符串 | +| [`DeserializeFromString`](deserialize-from-string.md) | 从字符串反序列化 | ### 事件 @@ -86,5 +89,5 @@ void SceneExample(Scene* scene) { ## 相关文档 - [Scene 模块总览](../scene.md) - Scene 模块总览 -- [SceneManager](scene-manager/scene-manager.md) - 场景管理器 -- [GameObject](../components/game-object/game-object.md) - 游戏对象 +- [SceneManager](../scene-manager/scene-manager.md) - 场景管理器 +- [GameObject](../../components/game-object/game-object.md) - 游戏对象 diff --git a/docs/api/scene/scene/serialize-to-string.md b/docs/api/scene/scene/serialize-to-string.md new file mode 100644 index 00000000..4eb219bf --- /dev/null +++ b/docs/api/scene/scene/serialize-to-string.md @@ -0,0 +1,33 @@ +# Scene::SerializeToString + +将场景序列化为字符串。 + +```cpp +std::string SerializeToString() const; +``` + +将场景的所有数据（包括所有 GameObject、组件和层级结构）序列化为 JSON 格式的字符串。 + +**返回：** `std::string` - 序列化后的 JSON 字符串 + +**线程安全：** ✅ (只读操作) + +**示例：** + +```cpp +#include + +using namespace XCEngine::Components; + +void Example(Scene* scene) { + std::string serialized = scene->SerializeToString(); + printf("Serialized scene (%zu bytes):\n%s\n", + serialized.size(), serialized.c_str()); +} +``` + +## 相关文档 + +- [Scene 总览](scene.md) - 返回类总览 +- [Load](load.md) - 从文件加载 +- [DeserializeFromString](deserialize-from-string.md) - 从字符串反序列化 diff --git a/docs/api/threading/task-system/task-system.md b/docs/api/threading/task-system/task-system.md index e8717e24..f406b3d9 100644 --- a/docs/api/threading/task-system/task-system.md +++ b/docs/api/threading/task-system/task-system.md @@ -24,8 +24,6 @@ | 方法 | 描述 | |------|------| -| [`TaskSystem()`](task-system.md) | 私有构造函数（单例） | -| [`~TaskSystem()`](task-system.md) | 析构函数 | | [`Initialize`](initialize.md) | 初始化任务系统 | | [`Shutdown`](shutdown.md) | 关闭任务系统 | | [`Submit(unique_ptr)`](submit.md) | 提交任务对象 |