diff --git a/packages/engine/Source/Core/GeometryFactory.js b/packages/engine/Source/Core/GeometryFactory.js index 10ee22d3cf1..519c21573f5 100644 --- a/packages/engine/Source/Core/GeometryFactory.js +++ b/packages/engine/Source/Core/GeometryFactory.js @@ -1,21 +1,70 @@ import DeveloperError from "../Core/DeveloperError.js"; /** - * Base class for all geometry creation utility classes that can be passed to {@link GeometryInstance} - * for asynchronous geometry creation. + * Describes a geometry type that can be converted into a {@link Geometry}. + *
+ * Implementations of this interface are the core geometry "description" classes
+ * such as {@link BoxGeometry}, {@link RectangleGeometry},
+ * {@link EllipsoidGeometry}, and other classes with a static
+ * createGeometry function. Instances of these classes can be
+ * passed to {@link GeometryInstance} and {@link Primitive} to have their
+ * vertices and indices created either asynchronously on a web worker or
+ * synchronously on the main thread.
+ *
+ * This type describes an interface and is not intended to be instantiated + * directly. + *
* + * @alias GeometryFactory * @constructor - * @class * @abstract + * + * @see BoxGeometry + * @see BoxOutlineGeometry + * @see CircleGeometry + * @see CircleOutlineGeometry + * @see CoplanarPolygonGeometry + * @see CoplanarPolygonOutlineGeometry + * @see CorridorGeometry + * @see CorridorOutlineGeometry + * @see CylinderGeometry + * @see CylinderOutlineGeometry + * @see EllipseGeometry + * @see EllipseOutlineGeometry + * @see EllipsoidGeometry + * @see EllipsoidOutlineGeometry + * @see FrustumGeometry + * @see FrustumOutlineGeometry + * @see GroundPolylineGeometry + * @see PlaneGeometry + * @see PlaneOutlineGeometry + * @see PolygonGeometry + * @see PolygonOutlineGeometry + * @see PolylineGeometry + * @see PolylineVolumeGeometry + * @see PolylineVolumeOutlineGeometry + * @see RectangleGeometry + * @see RectangleOutlineGeometry + * @see SimplePolylineGeometry + * @see SphereGeometry + * @see SphereOutlineGeometry + * @see WallGeometry + * @see WallOutlineGeometry */ function GeometryFactory() { DeveloperError.throwInstantiationError(); } /** - * Returns a geometry. + * Creates a {@link Geometry} from a geometry description. + *+ * Concrete geometry classes (for example {@link RectangleGeometry}) implement + * this function as a static method that takes an instance of the corresponding + * geometry description and returns the computed vertices and indices. + *
* - * @param {GeometryFactory} geometryFactory A description of the circle. + * @param {GeometryFactory} geometryFactory The geometry description to create. * @returns {Geometry|undefined} The computed vertices and indices. */ GeometryFactory.createGeometry = function (geometryFactory) { diff --git a/packages/engine/Source/Core/GeometryInstance.js b/packages/engine/Source/Core/GeometryInstance.js index d5316efdc7c..45958565c1a 100644 --- a/packages/engine/Source/Core/GeometryInstance.js +++ b/packages/engine/Source/Core/GeometryInstance.js @@ -14,6 +14,12 @@ import Matrix4 from "./Matrix4.js"; * * @param {object} options Object with the following properties: * @param {Geometry|GeometryFactory} options.geometry The geometry to instance. + * When a {@link Geometry} is passed, it will be used directly. When an + * object implementing {@link GeometryFactory} is passed (for example an + * instance of {@link RectangleGeometry} or {@link EllipsoidGeometry}), + * the actual geometry will be created either asynchronously on a web + * worker or synchronously on the main thread depending on the + * {@link Primitive} options. * @param {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] The model matrix that transforms to transform the geometry from model to world coordinates. * @param {object} [options.id] A user-defined object to return when the instance is picked with {@link Scene#pick} or get/set per-instance attributes with {@link Primitive#getGeometryInstanceAttributes}. * @param {object} [options.attributes] Per-instance attributes like a show or color attribute shown in the example below.