Merge pull request #67 from darwin-education/groundprimitive

Add GroundPrimitive and GroundPrimitiveCollection

docs/Guide.mdx

@@ -12,7 +12,7 @@ Resium brings React's component lifecycle to Cesium. The relationship between Ce
 1. `constructor`: The Cesium element is initialized (the Cesium element of some components are initialized at mount time).
 2. `render`: Nothing is rendered, because the object passed to children via React's context API does not exist in this time.
 3. `componentDidMount`: The Cesium element is mounted. After this, `forceUpdate` is called and re-render children.
-4. `render`: Children of the component are rendered. DOM never be rendered except root components (Viewer and CesiumWidget). 
+4. `render`: Children of the component are rendered. DOM never be rendered except root components (Viewer and CesiumWidget).
 5. `componentDidUpdate`: Changed properties of the Cesium element are updated. If "Cesium read only properties" are changed, the Cesium element will be reinitialized.
 6. `componentWillUnmount`: The Cesium element is unmounted and destroyed.
 
@@ -75,6 +75,7 @@ Exception are:
 - `ScreenSpaceEventHandler` > `ScreenSpaceEvent`
 - `xCollection` > `x`
 - `CustomDataSource` > `Entity`
+- `GroundPrimitiveCollection` > `GroundPrimitive`
 
 e.g.: `Scene` > `Camera` or `Camera` > `Entity` is not recommended.
 
@@ -182,14 +183,17 @@ const ExampleComponent = () => {
   let viewer; // Cesium.Viewer
 
   return (
-    <Viewer ref={e => { viewer = !!e ? e.cesiumElement : undefined; }} />
+    <Viewer
+      ref={e => {
+        viewer = !!e ? e.cesiumElement : undefined;
+      }}
+    />
   );
-}
+};
 ```
 
 ```jsx
 class ExampleComponent extends React.PureComponent {
-
   entity = React.createRef(); // entity.current = Cesium.Entity
 
   render() {
@@ -211,4 +215,4 @@ class ExampleComponent extends React.PureComponent {
 ## Limitations
 
 - Server side rendering is not supported. Cesium is rendered in web browsers.
-- Resium runs only with `react-dom`. because Cesium depends on APIs of web browsers (DOM, WebGL, Web Worker and so on). React Native is not supported. 
+- Resium runs only with `react-dom`. because Cesium depends on APIs of web browsers (DOM, WebGL, Web Worker and so on). React Native is not supported.

docs/scripts/generateDoc.js

@@ -82,9 +82,9 @@ ${type.summary ? `\n${type.summary}\n` : ""}
 ${
   type.noCesiumElement
     ? ""
-    : `**Cesium element**: [${type.name}](https://cesiumjs.org/Cesium/Build/Documentation/${
-        type.name
-      }.html)
+    : `**Cesium element**: [${type.cesiumElement ||
+        type.name}](https://cesiumjs.org/Cesium/Build/Documentation/${type.cesiumElement ||
+        type.name}.html)
 `
 }${
     /*
@@ -254,6 +254,11 @@ function detectComponentDescription(comments) {
           noCesiumElement: true,
         };
       }
+      if (/^ *?@cesiumElement/.test(c)) {
+        return {
+          cesiumElement: c.replace(/^ *?@cesiumElement/, "").trim(),
+        };
+      }
       if (/^ *?@summary/.test(c)) {
         return {
           summary: c.replace(/^ *?@summary/, "").trim(),

src/EntityDescription.ts

@@ -7,6 +7,8 @@ const { renderToStaticMarkup } = require("react-dom/server.browser");
 import { withCesium } from "./core/context";
 import { Entity } from "cesium";
 
+// @noCesiumElement
+
 /*
 @summary
 `EntityDescription` provides a way to render description of the entity with React.

src/GroundPrimitive.ts

@@ -0,0 +1,114 @@
+import Cesium from "cesium";
+
+import createCesiumComponent from "./core/CesiumComponent";
+import EventManager, { EventProps } from "./core/EventManager";
+
+/*
+@summary
+`GroundPrimitive` is a ground primitive in the `PrimitiveCollection`.
+
+Primitive is a low layer API for geographical visualization.
+[Entity](/components/entity) is more recommended unless performance issues.
+*/
+
+/*
+@scope
+Inside [Viewer](/components/Viewer), [CesiumWidget](/components/CesiumWidget), or [GroundPrimitiveCollection](/components/GroundPrimitiveCollection) component.
+If this component is inside GroundPrimitiveCollection component, a ground primitive object will be attached to the ground primitive collection of the scene.
+Otherwise, a primitive object will be attached to the PrimitiveCollection of the Viewer or CesiumWidget.
+*/
+
+export interface GroundPrimitiveCesiumProps {
+  appearance?: Cesium.Appearance;
+  debugShowBoundingVolume?: boolean;
+  debugShowShadowVolume?: boolean;
+  classificationType?: any; // Cesium.ClassificationType
+  depthFailAppearance?: Cesium.Appearance;
+  show?: boolean;
+}
+
+export interface GroundPrimitiveCesiumReadonlyProps {
+  allowPicking?: boolean;
+  asynchronous?: boolean;
+  compressVertices?: boolean;
+  geometryInstances?: Cesium.GeometryInstance[] | Cesium.GeometryInstance;
+  interleave?: boolean;
+  releaseGeometryInstances?: boolean;
+  vertexCacheOptimize?: boolean;
+}
+
+export interface GroundPrimitiveProps
+  extends GroundPrimitiveCesiumProps,
+    GroundPrimitiveCesiumReadonlyProps,
+    EventProps<any> {
+  // Cesium.GroundPrimitive
+  // Calls when [Primitive#readyPromise](https://cesiumjs.org/Cesium/Build/Documentation/GroundPrimitive.html#readyPromise) is fullfilled
+  onReady?: (primitive: any /* Cesium.GroundPrimitive */) => void;
+}
+
+export interface GroundPrimitiveContext {
+  primitiveCollection?: Cesium.PrimitiveCollection;
+  __RESIUM_EVENT_MANAGER?: EventManager;
+}
+
+const cesiumProps: (keyof GroundPrimitiveCesiumProps)[] = [
+  "appearance",
+  "classificationType",
+  "debugShowBoundingVolume",
+  "debugShowShadowVolume",
+  "depthFailAppearance",
+  "show",
+];
+
+const cesiumReadonlyProps: (keyof GroundPrimitiveCesiumReadonlyProps)[] = [
+  "allowPicking",
+  "asynchronous",
+  "compressVertices",
+  "geometryInstances",
+  "interleave",
+  "releaseGeometryInstances",
+  "vertexCacheOptimize",
+];
+
+const GroundPrimitive = createCesiumComponent<
+  any /* Cesium.GroundPrimitive */,
+  GroundPrimitiveProps,
+  GroundPrimitiveContext
+>({
+  name: "GroundPrimitive",
+  create(cprops, props) {
+    const primitive = new (Cesium as any).GroundPrimitive(cprops);
+    if (props.onReady) {
+      primitive.readyPromise.then(props.onReady);
+    }
+    return primitive;
+  },
+  mount(element, context, props) {
+    if (context.__RESIUM_EVENT_MANAGER) {
+      context.__RESIUM_EVENT_MANAGER.setEvents(element, props);
+    }
+    if (context.primitiveCollection) {
+      context.primitiveCollection.add(element);
+    }
+  },
+  update(element, props, prevProps, context) {
+    if (context.__RESIUM_EVENT_MANAGER) {
+      context.__RESIUM_EVENT_MANAGER.setEvents(element, props);
+    }
+  },
+  unmount(element, context) {
+    if (context.__RESIUM_EVENT_MANAGER) {
+      context.__RESIUM_EVENT_MANAGER.clearEvents(element);
+    }
+    if (context.primitiveCollection && !context.primitiveCollection.isDestroyed()) {
+      context.primitiveCollection.remove(element);
+    }
+    if (!element.isDestroyed()) {
+      element.destroy();
+    }
+  },
+  cesiumProps,
+  cesiumReadonlyProps,
+});
+
+export default GroundPrimitive;

src/GroundPrimitiveCollection.ts

@@ -0,0 +1,51 @@
+import Cesium from "cesium";
+
+import createCesiumComponent from "./core/CesiumComponent";
+
+// @cesiumElement PrimitiveCollection
+
+/*
+@summary
+`GroundPrimitiveCollection` is the collection of ground primitives of the scene.
+All properties are applied to single ground primitives collection of the scene.
+It can have some GroundPrimitive components as children.
+*/
+
+/*
+@scope
+Inside [Viewer](/components/Viewer) or [CesiumWidget](/components/CesiumWidget) components.
+*/
+
+export interface GroundPrimitiveCollectionCesiumProps {
+  show?: boolean;
+}
+
+export interface GroundPrimitiveCollectionProps extends GroundPrimitiveCollectionCesiumProps {
+  children?: React.ReactNode;
+}
+
+export interface GroundPrimitiveCollectionContext {
+  scene: Cesium.Scene;
+}
+
+const cesiumProps: (keyof GroundPrimitiveCollectionCesiumProps)[] = ["show"];
+
+const GroundPrimitiveCollection = createCesiumComponent<
+  Cesium.PrimitiveCollection,
+  GroundPrimitiveCollectionProps,
+  GroundPrimitiveCollectionContext
+>({
+  name: "GroundPrimitiveCollection",
+  create(cprops, props, context) {
+    return context.scene.groundPrimitives;
+  },
+  provide(element) {
+    return {
+      primitiveCollection: element,
+    };
+  },
+  cesiumProps,
+  setCesiumPropsAfterCreate: true,
+});
+
+export default GroundPrimitiveCollection;