XCSDD/docs/api/resources/importsettings/importsettings.md

# ImportSettings

**命名空间**: `XCEngine::Resources`

**类型**: `class` (abstract)

**描述**: 资源导入设置抽象基类，定义资源导入时的配置选项接口。

## 概述

`ImportSettings` 是所有资源导入设置的抽象基类。它提供了克隆和 JSON 序列化接口，允许不同资源类型定义各自的导入选项。引擎内置了两个具体实现：`TextureImportSettings` 和 `MeshImportSettings`。

## 公共方法

| 方法 | 描述 |
|------|------|
| `virtual Core::UniqueRef<ImportSettings> Clone() const = 0` | 克隆一份设置 |
| `virtual bool LoadFromJSON(const Containers::String& json)` | 从 JSON 加载设置（当前返回 false - stub） |
| `virtual Containers::String SaveToJSON() const` | 保存为 JSON 字符串（当前返回空字符串 - stub） |

---

## TextureImportSettings

纹理导入设置，继承自 `ImportSettings`。

**头文件**: `XCEngine/Resources/TextureImportSettings.h`

## 实现说明

**注意**: `LoadFromJSON()` 和 `SaveToJSON()` 当前为 stub 实现。

### 枚举类型

#### MipmapFilter

| 值 | 描述 |
|----|------|
| `Box` | Box 滤波器 |
| `Kaiser` | Kaiser 滤波器 |

#### CompressionQuality

| 值 | 描述 |
|----|------|
| `Low` | 低质量 |
| `Medium` | 中等质量 |
| `High` | 高质量 |
| `Ultra` | 超高质量 |

### 公共方法

| 方法 | 描述 |
|------|------|
| `void SetTextureType(TextureType type)` | 设置纹理类型 |
| `TextureType GetTextureType() const` | 获取纹理类型 |
| `void SetTargetFormat(TextureFormat format)` | 设置目标格式 |
| `TextureFormat GetTargetFormat() const` | 获取目标格式 |
| `void SetGenerateMipmaps(bool generate)` | 设置是否生成 Mipmap |
| `bool GetGenerateMipmaps() const` | 获取是否生成 Mipmap |
| `void SetMipmapFilter(MipmapFilter filter)` | 设置 Mipmap 滤波器 |
| `MipmapFilter GetMipmapFilter() const` | 获取 Mipmap 滤波器 |
| `void SetMaxAnisotropy(Core::uint32 anisotropy)` | 设置最大各向异性级别 |
| `Core::uint32 GetMaxAnisotropy() const` | 获取最大各向异性级别 |
| `void SetSRGB(bool srgb)` | 设置是否 sRGB |
| `bool GetSRGB() const` | 获取 sRGB 设置 |
| `void SetFlipVertical(bool flip)` | 设置是否垂直翻转 |
| `bool GetFlipVertical() const` | 获取垂直翻转设置 |
| `void SetFlipHorizontal(bool flip)` | 设置是否水平翻转 |
| `bool GetFlipHorizontal() const` | 获取水平翻转设置 |
| `void SetBorderColor(const Math::Vector3& color)` | 设置边框颜色 |
| `const Math::Vector3& GetBorderColor() const` | 获取边框颜色 |
| `void SetCompressionQuality(CompressionQuality quality)` | 设置压缩质量 |
| `CompressionQuality GetCompressionQuality() const` | 获取压缩质量 |
| `void SetUseHardwareCompression(bool use)` | 设置是否使用硬件压缩 |
| `bool GetUseHardwareCompression() const` | 获取硬件压缩设置 |
| `void SetMaxSize(Core::uint32 size)` | 设置最大纹理尺寸 |
| `Core::uint32 GetMaxSize() const` | 获取最大纹理尺寸 |
| `void SetGenerateNormalMap(bool generate)` | 设置是否生成法线贴图 |
| `bool GetGenerateNormalMap() const` | 获取法线贴图生成设置 |
| `void SetNormalMapStrength(float strength)` | 设置法线贴图强度 |
| `float GetNormalMapStrength() const` | 获取法线贴图强度 |

---

## MeshImportSettings

网格导入设置，继承自 `ImportSettings`。

**头文件**: `XCEngine/Resources/MeshImportSettings.h`

## 实现说明

**注意**: `LoadFromJSON()` 和 `SaveToJSON()` 当前为 stub 实现。

### MeshImportFlags

| 值 | 描述 |
|----|------|
| `None` | 无特殊标志 |
| `FlipUVs` | 翻转 UV 坐标 |
| `FlipWindingOrder` | 翻转绕序 |
| `GenerateNormals` | 生成法线 |
| `GenerateTangents` | 生成切线 |
| `OptimizeMesh` | 优化网格 |
| `ImportSkinning` | 导入骨骼蒙皮 |
| `ImportAnimations` | 导入动画 |
| `ImportMaterials` | 导入材质 |
| `ImportCameras` | 导入相机 |
| `ImportLights` | 导入灯光 |

支持位运算组合（`operator|`、`operator&`、`operator~`）。

### 公共方法

| 方法 | 描述 |
|------|------|
| `void SetImportFlags(MeshImportFlags flags)` | 设置导入标志 |
| `MeshImportFlags GetImportFlags() const` | 获取导入标志 |
| `void AddImportFlag(MeshImportFlags flag)` | 添加单个导入标志 |
| `void RemoveImportFlag(MeshImportFlags flag)` | 移除单个导入标志 |
| `bool HasImportFlag(MeshImportFlags flag) const` | 检查是否包含某标志 |
| `void SetScale(float scale)` | 设置缩放 |
| `float GetScale() const` | 获取缩放 |
| `void SetOffset(const Math::Vector3& offset)` | 设置偏移 |
| `const Math::Vector3& GetOffset() const` | 获取偏移 |
| `void SetAxisConversion(bool convert)` | 设置轴转换 |
| `bool GetAxisConversion() const` | 获取轴转换设置 |
| `void SetMergeMeshes(bool merge)` | 设置是否合并网格 |
| `bool GetMergeMeshes() const` | 获取合并网格设置 |
| `void SetOptimizeThreshold(float threshold)` | 设置优化阈值 |
| `float GetOptimizeThreshold() const` | 获取优化阈值 |
| `void SetImportScale(float scale)` | 设置导入缩放 |
| `float GetImportScale() const` | 获取导入缩放 |
| `void SetThreshold(float threshold)` | 设置阈值 |
| `float GetThreshold() const` | 获取阈值 |

## 使用示例

```cpp
#include <XCEngine/Resources/TextureImportSettings.h>
#include <XCEngine/Resources/MeshImportSettings.h>

// 纹理导入设置
TextureImportSettings texSettings;
texSettings.SetTextureType(TextureType::Texture2D);
texSettings.SetGenerateMipmaps(true);
texSettings.SetSRGB(true);
texSettings.SetCompressionQuality(CompressionQuality::High);
texSettings.SetMaxAnisotropy(16);

// 加载设置
texSettings.LoadFromJSON(R"({"sRGB":true,"maxAnisotropy":8})");

// 保存设置
Containers::String json = texSettings.SaveToJSON();

// 网格导入设置
MeshImportSettings meshSettings;
meshSettings.SetImportFlags(MeshImportFlags::FlipUVs | MeshImportFlags::GenerateNormals);
meshSettings.SetScale(1.0f);
meshSettings.SetAxisConversion(true);

// 使用设置加载资源
ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png", &texSettings);
ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("model.fbx", &meshSettings);
```

## 相关文档

- [IResourceLoader](../iloader/iloader.md) - 资源加载器
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
- [Resources 总览](../resources.md) - 返回模块总览