A primitive represents geometry in the Scene The geometry can be from a single GeometryInstance
as shown in example 1 below, or from an array of instances, even if the geometry is from different
geometry types, e.g., an RectangleGeometry and an EllipsoidGeometry as shown in Code Example 2.
A primitive combines geometry instances with an Appearance that describes the full shading, including
Material and RenderState Roughly, the geometry instance defines the structure and placement,
and the appearance defines the visual characteristics. Decoupling geometry and appearance allows us to mix
and match most of them and add a new geometry or appearance independently of each other.
Combining multiple instances into one primitive is called batching, and significantly improves performance for static data.
Instances can be individually picked; Scene#pick returns their GeometryInstance#id Using
per-instance appearances like PerInstanceColorAppearance, each instance can also have a unique color.
Geometry can either be created and batched on a web worker or the main thread. The first two examples
show geometry that will be created on a web worker by using the descriptions of the geometry. The third example
shows how to create the geometry on the main thread by explicitly calling the createGeometry method.
alias Primitive
{Object} [options] Object with the following properties:
{GeometryInstance[]|GeometryInstance} [options.geometryInstances] The geometry instances - or a single geometry instance - to render.
{Appearance} [options.appearance] The appearance used to render the primitive.
{Boolean} [options.show=true] Determines if this primitive will be shown.
{Matrix4} [options.modelMatrix=Matrix4.IDENTITY] The 4x4 transformation matrix that transforms the primitive (all geometry instances) from model to world coordinates.
{Boolean} [options.vertexCacheOptimize=false] When true, geometry vertices are optimized for the pre and post-vertex-shader caches.
{Boolean} [options.interleave=false] When true, geometry vertex attributes are interleaved, which can slightly improve rendering performance but increases load time.
{Boolean} [options.compressVertices=true] When true, the geometry vertices are compressed, which will save memory.
{Boolean} [options.releaseGeometryInstances=true] When true, the primitive does not keep a reference to the input geometryInstances to save memory.
{Boolean} [options.allowPicking=true] When true, each geometry instance will only be pickable with Scene#pick When false, GPU memory is saved.
{Boolean} [options.cull=true] When true, the renderer frustum culls and horizon culls the primitive's commands based on their bounding volume. Set this to false for a small performance gain if you are manually culling the primitive.
{Boolean} [options.asynchronous=true] Determines if the primitive will be created asynchronously or block until ready.
{Boolean} [options.debugShowBoundingVolume=false] For debugging only. Determines if this primitive's commands' bounding spheres are shown.
Annotations
@RawJSType()@native()@JSName("Cesium.Primitive")
Examples:
// 3. Create the geometry on the main thread.
scene.primitives.add(new Cesium.Primitive({
geometryInstances : new Cesium.GeometryInstance({
geometry : Cesium.EllipsoidGeometry.createGeometry(new Cesium.EllipsoidGeometry({
radii : new Cesium.Cartesian3(500000.0, 500000.0, 1000000.0),
vertexFormat : Cesium.VertexFormat.POSITION_AND_NORMAL
})),
modelMatrix : Cesium.Matrix4.multiplyByTranslation(Cesium.Transforms.eastNorthUpToFixedFrame(
Cesium.Cartesian3.fromDegrees(-95.59777, 40.03883)), new Cesium.Cartesian3(0.0, 0.0, 500000.0), new Cesium.Matrix4()),
id : 'ellipsoid',
attributes : {
color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.AQUA)
}
}),
appearance : new Cesium.PerInstanceColorAppearance()
}));
,
// 2. Draw different instances each with a unique color
var rectangleInstance = new Cesium.GeometryInstance({
geometry : new Cesium.RectangleGeometry({
rectangle : Cesium.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0),
vertexFormat : Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
}),
id : 'rectangle',
attributes : {
color : new Cesium.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5)
}
});
var ellipsoidInstance = new Cesium.GeometryInstance({
geometry : new Cesium.EllipsoidGeometry({
radii : new Cesium.Cartesian3(500000.0, 500000.0, 1000000.0),
vertexFormat : Cesium.VertexFormat.POSITION_AND_NORMAL
}),
modelMatrix : Cesium.Matrix4.multiplyByTranslation(Cesium.Transforms.eastNorthUpToFixedFrame(
Cesium.Cartesian3.fromDegrees(-95.59777, 40.03883)), new Cesium.Cartesian3(0.0, 0.0, 500000.0), new Cesium.Matrix4()),
id : 'ellipsoid',
attributes : {
color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.AQUA)
}
});
scene.primitives.add(new Cesium.Primitive({
geometryInstances : [rectangleInstance, ellipsoidInstance],
appearance : new Cesium.PerInstanceColorAppearance()
}));
,
// 1. Draw a translucent ellipse on the surface with a checkerboard pattern
var instance = new Cesium.GeometryInstance({
geometry : new Cesium.EllipseGeometry({
center : Cesium.Cartesian3.fromDegrees(-100.0, 20.0),
semiMinorAxis : 500000.0,
semiMajorAxis : 1000000.0,
rotation : Cesium.Math.PI_OVER_FOUR,
vertexFormat : Cesium.VertexFormat.POSITION_AND_ST
}),
id : 'object returned when this instance is picked and to get/set per-instance attributes'
});
scene.primitives.add(new Cesium.Primitive({
geometryInstances : instance,
appearance : new Cesium.EllipsoidSurfaceAppearance({
material : Cesium.Material.fromType('Checkerboard')
})
}));
A primitive represents geometry in the Scene The geometry can be from a single GeometryInstance as shown in example 1 below, or from an array of instances, even if the geometry is from different geometry types, e.g., an RectangleGeometry and an EllipsoidGeometry as shown in Code Example 2.
A primitive combines geometry instances with an Appearance that describes the full shading, including Material and RenderState Roughly, the geometry instance defines the structure and placement, and the appearance defines the visual characteristics. Decoupling geometry and appearance allows us to mix and match most of them and add a new geometry or appearance independently of each other.
Combining multiple instances into one primitive is called batching, and significantly improves performance for static data. Instances can be individually picked; Scene#pick returns their GeometryInstance#id Using per-instance appearances like PerInstanceColorAppearance, each instance can also have a unique color.
Geometry can either be created and batched on a web worker or the main thread. The first two examples show geometry that will be created on a web worker by using the descriptions of the geometry. The third example shows how to create the geometry on the main thread by explicitly calling the
createGeometrymethod.alias Primitive
true, geometry vertices are optimized for the pre and post-vertex-shader caches.true, geometry vertex attributes are interleaved, which can slightly improve rendering performance but increases load time.true, the geometry vertices are compressed, which will save memory.true, the primitive does not keep a reference to the inputgeometryInstancesto save memory.true, each geometry instance will only be pickable with Scene#pick Whenfalse, GPU memory is saved.true, the renderer frustum culls and horizon culls the primitive's commands based on their bounding volume. Set this tofalsefor a small performance gain if you are manually culling the primitive.// 3. Create the geometry on the main thread. scene.primitives.add(new Cesium.Primitive({ geometryInstances : new Cesium.GeometryInstance({ geometry : Cesium.EllipsoidGeometry.createGeometry(new Cesium.EllipsoidGeometry({ radii : new Cesium.Cartesian3(500000.0, 500000.0, 1000000.0), vertexFormat : Cesium.VertexFormat.POSITION_AND_NORMAL })), modelMatrix : Cesium.Matrix4.multiplyByTranslation(Cesium.Transforms.eastNorthUpToFixedFrame( Cesium.Cartesian3.fromDegrees(-95.59777, 40.03883)), new Cesium.Cartesian3(0.0, 0.0, 500000.0), new Cesium.Matrix4()), id : 'ellipsoid', attributes : { color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.AQUA) } }), appearance : new Cesium.PerInstanceColorAppearance() }));
// 2. Draw different instances each with a unique color var rectangleInstance = new Cesium.GeometryInstance({ geometry : new Cesium.RectangleGeometry({ rectangle : Cesium.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0), vertexFormat : Cesium.PerInstanceColorAppearance.VERTEX_FORMAT }), id : 'rectangle', attributes : { color : new Cesium.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5) } }); var ellipsoidInstance = new Cesium.GeometryInstance({ geometry : new Cesium.EllipsoidGeometry({ radii : new Cesium.Cartesian3(500000.0, 500000.0, 1000000.0), vertexFormat : Cesium.VertexFormat.POSITION_AND_NORMAL }), modelMatrix : Cesium.Matrix4.multiplyByTranslation(Cesium.Transforms.eastNorthUpToFixedFrame( Cesium.Cartesian3.fromDegrees(-95.59777, 40.03883)), new Cesium.Cartesian3(0.0, 0.0, 500000.0), new Cesium.Matrix4()), id : 'ellipsoid', attributes : { color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.AQUA) } }); scene.primitives.add(new Cesium.Primitive({ geometryInstances : [rectangleInstance, ellipsoidInstance], appearance : new Cesium.PerInstanceColorAppearance() }));
// 1. Draw a translucent ellipse on the surface with a checkerboard pattern var instance = new Cesium.GeometryInstance({ geometry : new Cesium.EllipseGeometry({ center : Cesium.Cartesian3.fromDegrees(-100.0, 20.0), semiMinorAxis : 500000.0, semiMajorAxis : 1000000.0, rotation : Cesium.Math.PI_OVER_FOUR, vertexFormat : Cesium.VertexFormat.POSITION_AND_ST }), id : 'object returned when this instance is picked and to get/set per-instance attributes' }); scene.primitives.add(new Cesium.Primitive({ geometryInstances : instance, appearance : new Cesium.EllipsoidSurfaceAppearance({ material : Cesium.Material.fromType('Checkerboard') }) }));
Appearance
GeometryInstance