new Primitive()

The underlying API class geometry used for efficient rendering of 3D geometry can be a single GeometrySample (as shown in Example 1 below), or an array composed of multiple instances, even if these geometries belong to different geometry types, such as RectangleGeometry and EllipsoidGeometry shown in Code Example 2. A prototype combines geometric instances with Appearance, which describes the complete shadow, including Material and RenderState. Roughly speaking, geometric instances define structure and position, while appearance defines visual features. After decoupling the geometry and appearance, we can mix and match most of them, and independently add new geometry or appearance. Merging multiple instances into one primitive is called batch processing, which can significantly improve the performance of static data. Examples can be selected separately; Scene # pick returns its GeometryInstance # id. Using the appearance of each instance, such as PerInstanceColorAppearance, each instance can also have a unique color. Geometry can be created and batch processed on web workers or main threads. The first two examples demonstrate the geometry that will be created on a web worker using descriptions of geometric shapes. The third example demonstrates how to create geometry on the main thread by explicitly calling the creatGeometry method.

Name	Type	Default	Description
`options.geometryInstances`	Array.<GeometryInstance> \| GeometryInstance		optional Geometric instance to render - or a single geometric instance.
`options.appearance`	Appearance		optional Used to render the appearance of primitives.
`options.show`	Boolean	true	optional Decide whether to display the primitive.
`options.modelMatrix`	Matrix4	Matrix4.IDENTITY	optional 4x4 transformation matrix, used to transform primitives (all geometric instances) from model coordinates to geographic coordinates.
`options.vertexCacheOptimize`	Boolean	false	optional When true, geometric vertices will be optimized for pre - and post vertex shader caching.
`options.interleave`	Boolean	false	optional When true, geometric vertex attributes will be displayed in a staggered manner, which can slightly improve rendering performance but increase loading time.
`options.compressVertices`	Boolean	true	optional When true, geometric vertices will be compressed to save memory.
`options.releaseGeometryInstances`	Boolean	true	optional When true, the primitive does not retain a reference to the input geometriInstances to save memory.
`options.allowPicking`	Boolean	true	optional When true, each geometric instance can only be selected using Scene # pick. False means saving GPU memory.
`options.cull`	Boolean	true	optional When true, the renderer's frustum and horizon will exclude their commands based on the primitive's boundary volume. If the primitive is manually removed, set it to false to achieve a smaller performance gain.
`options.asynchronous`	Boolean	true	optional Decide whether the primitive is created asynchronously or blocked until it is ready.
`options.debugShowBoundingVolume`	Boolean	false	optional Only for debugging purposes. Determine whether to display the command bounding ball for the primitive.
`options.shadows`	ShadowMode	ShadowMode.DISABLED	optional Determine whether the prototype is projecting or receiving shadows from various light sources.

See:

GeometryInstance
Appearance

Examples

// 1. Draw a translucent ellipse on the surface with a checkerboard pattern
var instance = new SuperMap3D.GeometryInstance({
  geometry : new SuperMap3D.EllipseGeometry({
      center : SuperMap3D.Cartesian3.fromDegrees(-100.0, 20.0),
      semiMinorAxis : 500000.0,
      semiMajorAxis : 1000000.0,
      rotation : SuperMap3D.Math.PI_OVER_FOUR,
      vertexFormat : SuperMap3D.VertexFormat.POSITION_AND_ST
  }),
  id : 'object returned when this instance is picked and to get/set per-instance attributes'
});
scene.primitives.add(new SuperMap3D.Primitive({
  geometryInstances : instance,
  appearance : new SuperMap3D.EllipsoidSurfaceAppearance({
    material : SuperMap3D.Material.fromType('Checkerboard')
  })
}));

// 2. Draw different instances each with a unique color
var rectangleInstance = new SuperMap3D.GeometryInstance({
  geometry : new SuperMap3D.RectangleGeometry({
    rectangle : SuperMap3D.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0),
    vertexFormat : SuperMap3D.PerInstanceColorAppearance.VERTEX_FORMAT
  }),
  id : 'rectangle',
  attributes : {
    color : new SuperMap3D.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5)
  }
});
var ellipsoidInstance = new SuperMap3D.GeometryInstance({
  geometry : new SuperMap3D.EllipsoidGeometry({
    radii : new SuperMap3D.Cartesian3(500000.0, 500000.0, 1000000.0),
    vertexFormat : SuperMap3D.VertexFormat.POSITION_AND_NORMAL
  }),
  modelMatrix : SuperMap3D.Matrix4.multiplyByTranslation(SuperMap3D.Transforms.eastNorthUpToFixedFrame(
    SuperMap3D.Cartesian3.fromDegrees(-95.59777, 40.03883)), new SuperMap3D.Cartesian3(0.0, 0.0, 500000.0), new SuperMap3D.Matrix4()),
  id : 'ellipsoid',
  attributes : {
    color : SuperMap3D.ColorGeometryInstanceAttribute.fromColor(SuperMap3D.Color.AQUA)
  }
});
scene.primitives.add(new SuperMap3D.Primitive({
  geometryInstances : [rectangleInstance, ellipsoidInstance],
  appearance : new SuperMap3D.PerInstanceColorAppearance()
}));

// 3. Create the geometry on the main thread.
scene.primitives.add(new SuperMap3D.Primitive({
  geometryInstances : new SuperMap3D.GeometryInstance({
      geometry : SuperMap3D.EllipsoidGeometry.createGeometry(new SuperMap3D.EllipsoidGeometry({
        radii : new SuperMap3D.Cartesian3(500000.0, 500000.0, 1000000.0),
        vertexFormat : SuperMap3D.VertexFormat.POSITION_AND_NORMAL
      })),
      modelMatrix : SuperMap3D.Matrix4.multiplyByTranslation(SuperMap3D.Transforms.eastNorthUpToFixedFrame(
        SuperMap3D.Cartesian3.fromDegrees(-95.59777, 40.03883)), new SuperMap3D.Cartesian3(0.0, 0.0, 500000.0), new SuperMap3D.Matrix4()),
      id : 'ellipsoid',
      attributes : {
        color : SuperMap3D.ColorGeometryInstanceAttribute.fromColor(SuperMap3D.Color.AQUA)
      }
  }),
  appearance : new SuperMap3D.PerInstanceColorAppearance()
}));

Members

readonly allowPickingBoolean

When true, each geometric instance can only be selected using Scene # pick. When false, save GPU memory.

Default Value:

appearanceAppearance

Appearance used for shading the primitive. Each geometry is colored with the same appearance. Some appearances, such as PerInstanceColorAppearance, can assign unique properties to each instance.

Default Value:

readonly asynchronousBoolean

Determine whether to create and batch geometry instances on the web worker.

Default Value:

readonly compressVerticesBoolean

When true, geometric vertices are compressed, which saves memory.

Default Value:

cullBoolean

When true, the renderer's frustum and horizon will exclude their commands based on the boundary volume of the primitive. If the primitive is manually removed, set it to false to obtain a smaller performance gain.

Default Value:

debugShowBoundingVolumeBoolean

This property is only for debugging purposes; It is not intended for production and has not been optimized.

Draw a bounding ball for each drawing command in the primitive.

Default Value:

depthFailAppearanceAppearance

When the primitive fails the depth test, Appearance is used to mask the primitive. Each geometric instance has shadows with the same appearance. Some appearances, such as PerInstanceColorAppearance, allow assigning unique properties to each instance.

When using appearances that require color attributes, such as PerInstanceColorAppearance, add the depthFailed Color attribute for each instance.

The EXT_frag_depth WebGL extension is required for proper rendering. If this extension is not supported, artifacts may occur.

Default Value:

geometryInstancesArray.<GeometryInstance> GeometryInstance

The geometric instance rendered by this primitive. If options.leaseGeometryInstances is true when building primitives, it may not be defined.

Changing this property after rendering the primitive will not have any impact.

Default Value:

readonly interleaveBoolean

Determining whether geometric vertex attributes are interlaced can slightly improve rendering performance.

Default Value:

modelMatrixMatrix4

Convert the primitives (all geometric instances) from model coordinates to geographic coordinates using a 4x4 transformation matrix. When the matrix is the same matrix, the elements will be plotted in geographic coordinates, i.e. WGS84 coordinates. Local reference frames can be used by providing different transformation matrices, such as the matrix returned by Transforms.eastNorthUpToFixedFrame.

This attribute is only supported in 3D mode.

Default Value:

Example

var origin = SuperMap3D.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
p.modelMatrix = SuperMap3D.Transforms.eastNorthUpToFixedFrame(origin);

readonly readyBoolean

Determine if the primitives have been completed and are ready for rendering. If this property is true, the primitive will be rendered the next time Primitive # update is called.

readonly readyPromisePromise.<Primitive>

Get a Promise that will be parsed when the primitive is ready for rendering.

readonly releaseGeometryInstancesBoolean

When true, the primitive does not retain references to the input to save memory.

Default Value:

shadowsShadowMode

Determine whether this primitive projects or receives shadows from each light source.

Default Value:

showBoolean

Decide whether to display the base surface. This will affect all geometric instances in the primitive.

Default Value:

readonly vertexCacheOptimizeBoolean

When true, the geometric vertices will be optimized for the tiles before and after the vertex shader.

Default Value:

Methods

destroy(){undefined}

Destroy the WebGL resources held by the object. Destroying an object can release WebGL resources deterministically, rather than relying on a garbage collector to destroy the object.

Once the object is destroyed, it cannot be used again; Calling any function other than isDestroyed will result in a Developer Error exception. Therefore, please assign the return value (undefined) to the object using the method shown in the example.

See:

Primitive#isDestroyed

Throws:

The object has been destroyed, i.e. destroy() has been called.
Type DeveloperError

Returns:

Type	Description
undefined

Example

e = e && e.destroy();

getGeometryInstanceAttributes(id){Object}

Returns the modifiable per-instance attributes for a GeometryInstance.

Name	Type	Description
`id`	*	The id of the `GeometryInstance`.

Throws:

must call update before calling getGeometryInstanceAttributes.
Type DeveloperError

Returns:

Type	Description
Object	The typed array in the attribute's format or undefined if the is no instance with id.

Example

var attributes = primitive.getGeometryInstanceAttributes('an id');
attributes.color = SuperMap3D.ColorGeometryInstanceAttribute.toValue(SuperMap3D.Color.AQUA);
attributes.show = SuperMap3D.ShowGeometryInstanceAttribute.toValue(true);
attributes.distanceDisplayCondition = SuperMap3D.DistanceDisplayConditionGeometryInstanceAttribute.toValue(100.0, 10000.0);
attributes.offset = SuperMap3D.OffsetGeometryInstanceAttribute.toValue(Cartesian3.IDENTITY);

isDestroyed(){Boolean}

If the object has been destroyed, return true; Otherwise, return false.

If the object has been destroyed, it should not be used; Calling any function other than isDestroyed will result in a Developer Error exception.

See:

Primitive#destroy

Returns:

Type	Description
Boolean	If the object has been destroyed, it is true; Otherwise, it is false.

update()

Called when Viewer or Widget render the scene to get the draw commands needed to render this primitive.

Do not call this function directly. This is documented just to list the exceptions that may be propagated when the scene is rendered:

Throws:

All instance geometries must have the same primitiveType.

Type

DeveloperError
Appearance and material have a uniform with the same name.

Type

DeveloperError
Primitive.modelMatrix is only supported in 3D mode.

Type

DeveloperError
Vertex texture fetch support is required to render primitives with per-instance attributes. The maximum number of vertex texture image units must be greater than zero.

Type

RuntimeError

Class: Primitive

new Primitive()

Examples

Members

readonly allowPickingBoolean

appearanceAppearance

readonly asynchronousBoolean

readonly compressVerticesBoolean

cullBoolean

debugShowBoundingVolumeBoolean

depthFailAppearanceAppearance

geometryInstancesArray.<GeometryInstance> GeometryInstance

readonly interleaveBoolean

modelMatrixMatrix4

Example

readonly readyBoolean

readonly readyPromisePromise.<Primitive>

readonly releaseGeometryInstancesBoolean

shadowsShadowMode

showBoolean

readonly vertexCacheOptimizeBoolean

Methods

destroy(){undefined}

Throws:

Returns:

Example

getGeometryInstanceAttributes(id){Object}

Throws:

Returns:

Example

isDestroyed(){Boolean}

Returns:

update()

Throws: