## 图元 Primitive

>  Cesium中的绘制矢量图形的API可以分为两类：Entity、Primitive。

### 1.简介

`Primitive` API 是面向图形开发人员的低层次API，被设计成为各种类型要素提供高效和灵活的可视化功能，对比`Entity` API 具有更高的效率，具有以下优点：

- 高性能。绘制大量`Primitive`时，可以将其合并为单个`Geometry`，以减少CPU的计算量，更好的使用GPU处理。合并 `Primitive`由 Web worker 线程执行，用户界面保持响应。
- 灵活性。
- 低级别访问。易于修改GLSL顶点、片段着色器、使用自定义的渲染状态。

### 2. 组成

一个` Primitive` 由 `geometryInstance` 和一个 `Appearance` (包含 `Material` 材料和和`RenderState`渲染状态)组成，代表`Scene`场景中的一个`geometry`几何对象。

- geometry实例定义了结构和位置;
- Appearance定义了视觉特征。



`Primitive`主要配置项options:

- geometryInstances ：几何实例
-  appearance ：外观，appearance定义了着色器（sharding），包含了完整的GLSL顶点着色器和片段着色器以及用于绘制primitive的渲染状态
- show : 是否展示
- allowPicking ：是否允许被拾取
- asynchronous ：异步
- shadows ：确定此primitive是否投射或接收来自光源的阴影。ShadowMode.DISABLED
-  releaseGeometryInstances:是否清空原来的geometryInstances,清除后无法获取几何实例的属性。

其中geometryInstances 可以是一个[GeometryInstance](https://cesium.com/learn/cesiumjs/ref-doc/GeometryInstance.html)实例或是geometryInstance 数组。将多个geometryInstance组合成一个Primitive称为`batching`，可以显著提高静态数据的性能。

```javascript
viewer.scene.primitives.add(new Cesium.Primitive({
    geometryInstances : new Cesium.GeometryInstance({
        geometry: new Cesium.PolylineGeometry({
            positions : Cesium.Cartesian3.fromDegreesArray([
                112, 23,
                122, 24,
                130, 22,
                112, 20
            ]),
            width : 10.0,
            //指定线段每段的颜色，数量必须与线段数相同
            colors:[Cesium.Color.RED,Cesium.Color.THISTLE,Cesium.Color.TURQUOISE],
        }),
        // attributes : {
        //   // 通过attributes属性统一指定线段颜色
        //   color : Cesium.ColorGeometryInstanceAttribute.fromColor(new Cesium.Color(1.0, 1.0, 1.0, 0.6))
        // },
        id:"线要素"
    }),
    // PolylineColorAppearance : 使用每顶点或者每片段的颜色来着色多线段。可以用于渲染 PolylineGeometry or GroundPolylineGeometry. 
    appearance : new Cesium.PolylineColorAppearance({
        translucent : false,
    })
}));

```

实例也可以单独的被拾取(picked)到。

```javascript
viewer.screenSpaceEventHandler.setInputAction(function (e) {
    // topPrimitive包含{id,primitive}
    let topPrimitive = viewer.scene.pick(e.position)
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

```

使用Scene场景的picked方法可以获得到geometry实例的id,也可以使用appearance的实例定义primitive的外表。

<img src="./images/image-20230322141314417.png" alt="image-20230322141314417" style="zoom: 80%;" />



### 3.几何实例

`GeometryInstance` 实例的配置项：

- geometry ：几何实例对象.
- modelMatrix ：将geometry从模型转换为世界坐标的模型矩阵
- id ：是一个用户自定义的Object对象(可以用于存储自定义属性)，当geometryInstance 被 Scene#pick 拾取到时会被返回 or get/set per-instance attributes with Primitive#getGeometryInstanceAttributes.
-  attributes ：每个实例的属性，如下面示例中的显示或颜色属性。

其中geometry 的基础配置项Options和类型：

- attributes :是一个GeometryAttributes类型
- primitiveType ：可选值：POINTS、LINES、LINE_LOOP、LINE_STRIP、TRIANGLES、TRIANGLE_STRIP、TRIANGLE_FAN
- indices :是一个  Uint16Array | Uint32Array 用于确定几何图形中的primitive的可选索引数据.
-  boundingSphere :  BoundingSphere   一个可选的将几何图形完全包围的边界球

类型：

| Geometry                 | Outline                         | Description                                                  |
| :----------------------- | :------------------------------ | :----------------------------------------------------------- |
| `BoxGeometry`            | `BoxOutlineGeometry`            | A box                                                        |
| `CircleGeometry`         | `CircleOutlineGeometry`         | A circle or extruded circle                                  |
| `CorridorGeometry`       | `CorridorOutlineGeometry`       | A polyline normal to the surface with a width in meters and optional extruded height |
| `CylinderGeometry`       | `CylinderOutlineGeometry`       | A cylinder, cone, or truncated cone                          |
| `EllipseGeometry`        | `EllipseOutlineGeometry`        | An ellipse or extruded ellipse                               |
| `EllipsoidGeometry`      | `EllipsoidOutlineGeometry`      | An ellipsoid                                                 |
| `RectangleGeometry`      | `RectangleOutlineGeometry`      | An rectangle or extruded rectangle                           |
| `PolygonGeometry`        | `PolygonOutlineGeometry`        | A polygon with optional holes or extruded polygon            |
| `PolylineGeometry`       | `SimplePolylineGeometry`        | A collection of line segments with a width in pixels         |
| `PolylineVolumeGeometry` | `PolylineVolumeOutlineGeometry` | A 2D shape extruded along a polyline                         |
| `SphereGeometry`         | `SphereOutlineGeometry`         | A sphere                                                     |
| `WallGeometry`           | `WallOutlineGeometry`           | A wall perpendicular to the globe                            |



- PolylineGeometry ：线要素
- SimplePolylineGeometry : 轮廓线
- PolygonGeometry ：面要素
- RectangleGeometry ：矩形
- EllipseGeometry ：椭圆
- CircleGeometry ：圆形
- WallGeometry
- BoxGeometry
- EllipsoidGeometry







### 4. Appearance

基础配置项options:

- translucent ：geometry 应该是半透明的，所以 Appearance#renderState启用了alpha混合
- closed ：是否关闭渲染状态
- material ：材质
- vertexShaderSource ：
- fragmentShaderSource ：
- renderState ：渲染状态

类型：

- MaterialAppearance ：支持各种geometry类型的外观，支持使用材质来定义着色
-  EllipsoidSurfaceAppearance ：是MaterialAppearance的一个版本。假设几何图形与地面是平行的，并且以此来进行顶点属性的计算
- PerInstanceColorAppearance ：让每个实例使用自定义的颜色着色
- PolylineColorAppearance : 使用每顶点或者每片段的颜色来着色多线段。可以用于渲染 PolylineGeometry or GroundPolylineGeometry. 
- PolylineMaterialAppearance : 支持使用材质来着色多线段。PolylineGeometry支持材质渲染的类





| name |











### 参考文章

[1] Cesium快速上手6-Primitive图元的讲解https://www.jianshu.com/p/5e9cce778690