材质与渲染工具（Materials & Utils）

提供自定义材质注册、动态材质属性、离屏渲染工具以及底图图层工厂等功能。

---

CsmMaterial — 材质注册器

静态类，通过 Cesium.Material._materialCache.addMaterial 注册自定义 GLSL 材质。

方法：

CsmMaterial.addMaterial(options: MaterialOptions): void

参数：

参数	类型	说明
type	string	材质类型名称（如 'EllipsoidMove'）
fabric.type	string	Fabric 材质类型标识
fabric.uniforms	Record<string, any>	材质 uniform 初始值
fabric.source	string	GLSL shader 源码

示例：

import { CsmMaterial } from './materials/Material'

// 注册自定义材质
CsmMaterial.addMaterial({
  type: 'MyCustomMaterial',
  fabric: {
    type: 'MyCustomMaterial',
    uniforms: {
      color: new Cesium.Color(1.0, 0.0, 0.0, 1.0),
      speed: 1.0
    },
    source: `
      czm_material czm_getMaterial(czm_materialInput materialInput) {
        czm_material material = czm_getDefaultMaterial(materialInput);
        material.diffuse = vec3(1.0, 0.0, 0.0);
        return material;
      }
    `
  }
})

// 使用材质
entity.polyline.material = new Cesium.Material({
  fabric: { type: 'MyCustomMaterial' }
})

注意： 注册后可通过 Cesium.Material.MyCustomMaterialType 访问材质类型常量。

---

PolylineDashMoveMaterialProperty — 移动虚线折线材质

支持动画移动效果的虚线折线材质。底层 GLSL 位于 Shaders/PolylineDashMoveMaterial.glsl。

构造参数：

interface PolylineDashMoveMaterialPropertyOptions {
  color?: Cesium.Color | Cesium.Property   // 线段颜色，默认 WHITE
  gapColor?: Cesium.Color | Cesium.Property // 间隔颜色，默认 TRANSPARENT
  dashLength?: number | Cesium.Property     // 虚线长度，默认 16.0
  dashPattern?: number | Cesium.Property    // 虚线图案，默认 255.0
}

参数表：

选项	类型	默认值	说明
color	Color | Property	Color.WHITE	线段颜色
gapColor	Color | Property	Color.TRANSPARENT	间隔颜色
dashLength	number | Property	16.0	每段虚线长度
dashPattern	number | Property	255.0	虚线图案掩码

示例：

entity.polyline.material = new PolylineDashMoveMaterialProperty({
  color: Cesium.Color.CYAN,
  dashLength: 32,
  dashPattern: 255
})

---

EllipsoidMoveMaterialProperty — 移动椭球体轮廓材质

支持动画移动效果的椭球体轮廓材质。底层 GLSL 位于 Shaders/EllipsoidMoveMaterial.glsl。

构造参数：

interface EllipsoidMoveMaterialPropertyOptions {
  color?: Cesium.Color | Cesium.Property   // 轮廓颜色，默认 WHITE
  speed?: number | Cesium.Property         // 移动速度
}

参数表：

选项	类型	默认值	说明
color	Color | Property	Color.WHITE	椭球轮廓颜色
speed	number | Property	—	动画移动速度

示例：

entity.ellipsoid.material = new EllipsoidMoveMaterialProperty({
  color: Cesium.Color.MAGENTA
})

---

离屏渲染工具

createFrameBuffer — 创建帧缓冲对象

创建 Cesium Framebuffer，用于离屏渲染。

import { createFrameBuffer } from './utils/createFrameBuffer'

const fbo = createFrameBuffer(viewer.scene)
// fbo 的颜色纹理尺寸与 drawingBuffer 一致

参数：

参数	类型	说明
scene	Cesium.Scene	Cesium 场景对象

内部实现： 创建 Cesium.Texture（RGBA，drawingBuffer 尺寸）作为颜色附件。

createFboCamera — 创建离屏渲染相机

创建独立 Camera 用于离屏渲染。

import { createFboCamera } from './utils/createFboCamera'

const camera = createFboCamera(viewer.scene, true) // frustumBool=true 显示调试相机

参数：

参数	类型	默认值	说明
scene	Cesium.Scene	—	场景对象
frustumBool	boolean	false	是否显示调试相机线框（DebugCameraPrimitive）

默认相机位置： (126.30°, 35.02°, 200km)，东北天视角。

示例（结合离屏渲染 Mixin）：

import { createFrameBuffer } from './utils/createFrameBuffer'
import { createFboCamera } from './utils/createFboCamera'

// 创建离屏渲染资源
const fbo = createFrameBuffer(viewer.scene)
const camera = createFboCamera(viewer.scene)
const canvas = document.createElement('canvas')
canvas.width = 512
canvas.height = 512

// 单次渲染
viewer.renderToCanvas(fbo, camera, canvas)

// 实时帧同步渲染
viewer.startRealTimeRenderToCanvas(fbo, camera, canvas)
// viewer.endRealTimeRenderToCanvas()  // 停止

---

getAssetUrl — 资源路径解析

解析 Vite 项目静态资源路径，将 @/ 别名转为相对路径。

import { getAssetUrl } from './tools/asset'

const url = getAssetUrl('@/assets/maps/world.png')
// 返回: '/src/assets/maps/world.png'

参数：

参数	类型	说明
path	string	资源路径（支持 @/ 别名）

---

BaseLayerProvider — 底图图层工厂

提供预设底图和自定义底图的创建，支持多种地图服务类型。

静态方法：

方法	返回类型	说明
BaseLayerProvider.create(config, options?)	ImageryProvider | null	创建底图提供者
BaseLayerProvider.getPresets()	PresetLayerInfo[]	获取预设底图列表
BaseLayerProvider.createFromUrl(url)	ImageryProvider | null	智能识别 URL 类型并创建

预设类型（PresetBaseLayerType）：

类型	别名	说明
'osm'	'openstreetmap'	OpenStreetMap 标准瓦片
'gaode-img'	'gaode'	高德影像地图
'gaode-vec'	—	高德矢量地图
'none'	'null' / 'false'	无底图

自定义类型（CustomBaseLayerType）：

类型	别名	说明
'xyz'	'url' / 'tile'	XYZ 瓦片服务
'wms'	—	OGC WMS 服务
'arcgis'	—	ArcGIS MapServer
'single'	'image'	单张图片底图

示例：

import { BaseLayerProvider } from './providers/BaseLayerProvider'

// 预设底图
const osmProvider = BaseLayerProvider.create('osm')

// 高德影像
const gaodeProvider = BaseLayerProvider.create('gaode-img')

// 自定义 XYZ 瓦片
const customProvider = BaseLayerProvider.create({
  type: 'xyz',
  url: 'https://example.com/{z}/{x}/{y}.png',
  maximumLevel: 19
})

// 获取预设列表
const presets = BaseLayerProvider.getPresets()
// [{ key: 'osm', name: 'OpenStreetMap', needToken: false }, ...]

参数表（CustomBaseLayerConfig）：

属性	类型	必填	说明
type	CustomBaseLayerType	是	服务类型
url	string	是	服务 URL
layers	string	否	WMS 图层名称
maximumLevel	number	否	最大缩放级别
minimumLevel	number	否	最小缩放级别
tileWidth	number	否	瓦片宽度（single 类型）
tileHeight	number	否	瓦片高度（single 类型）
rectangle	Rectangle	否	矩形范围（single 类型）
subdomains	string[]	否	子域名列表
credit	string	否	版权信息