518 lines
16 KiB
JavaScript
518 lines
16 KiB
JavaScript
// @ts-check
|
|
|
|
import assert from "../Core/assert.js";
|
|
import Check from "../Core/Check.js";
|
|
import defined from "../Core/defined.js";
|
|
import BufferPrimitive from "./BufferPrimitive.js";
|
|
import BufferPrimitiveCollection from "./BufferPrimitiveCollection.js";
|
|
|
|
/** @import { TypedArray, TypedArrayConstructor } from "../Core/globalTypes.js"; */
|
|
/** @import BufferPolygonCollection from "./BufferPolygonCollection.js"; */
|
|
|
|
const { ERR_CAPACITY, ERR_RESIZE, ERR_OUT_OF_RANGE } =
|
|
BufferPrimitiveCollection.Error;
|
|
|
|
/**
|
|
* View bound to the underlying buffer data of a {@link BufferPolygonCollection}.
|
|
*
|
|
* <p>BufferPolygon instances are {@link https://en.wikipedia.org/wiki/Flyweight_pattern|flyweights}:
|
|
* a single BufferPolygon instance can be temporarily bound to any conceptual
|
|
* "polygon" in a BufferPolygonCollection, allowing very large collections to be
|
|
* iterated and updated with a minimal memory footprint.</p>
|
|
*
|
|
* <p>Represented as one (1) external linear ring of three (3) or more positions.
|
|
* May optionally define one or more internal linear rings ("holes") within the
|
|
* polygon. Each hole is represented as a single index into the positions array,
|
|
* where the vertex at that index is the start of an internal linear ring that
|
|
* continues along the following vertices until reaching either the vertex
|
|
* index of the next hole, or the end of the vertex list. Stores a precomputed
|
|
* triangulation, represented as three vertex indices per triangle.</p>
|
|
*
|
|
* @see BufferPolygonCollection
|
|
* @see BufferPolygonMaterial
|
|
* @see BufferPrimitive
|
|
* @extends BufferPrimitive
|
|
* @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
|
|
*/
|
|
class BufferPolygon extends BufferPrimitive {
|
|
/**
|
|
* @type {BufferPolygonCollection}
|
|
* @ignore
|
|
*/
|
|
_collection = null;
|
|
|
|
/** @ignore */
|
|
static Layout = {
|
|
...BufferPrimitive.Layout,
|
|
|
|
/**
|
|
* Offset in collection position array to first vertex in polygon, number
|
|
* of VEC3 elements.
|
|
* @type {number}
|
|
* @ignore
|
|
*/
|
|
POSITION_OFFSET_U32: BufferPrimitive.Layout.__BYTE_LENGTH,
|
|
|
|
/**
|
|
* Count of positions (vertices) in this polygon, number of VEC3 elements.
|
|
* @type {number}
|
|
* @ignore
|
|
*/
|
|
POSITION_COUNT_U32: BufferPrimitive.Layout.__BYTE_LENGTH + 4,
|
|
|
|
/**
|
|
* Offset in collection holes array to first hole in polygon, number of
|
|
* integer elements.
|
|
* @type {number}
|
|
* @ignore
|
|
*/
|
|
HOLE_OFFSET_U32: BufferPrimitive.Layout.__BYTE_LENGTH + 8,
|
|
|
|
/**
|
|
* Count of holes (indices) in this polygon.
|
|
* @type {number}
|
|
* @ignore
|
|
*/
|
|
HOLE_COUNT_U32: BufferPrimitive.Layout.__BYTE_LENGTH + 12,
|
|
|
|
/**
|
|
* Offset in collection triangles array to first triangle in polygon,
|
|
* number of VEC3 elements.
|
|
* @type {number}
|
|
* @ignore
|
|
*/
|
|
TRIANGLE_OFFSET_U32: BufferPrimitive.Layout.__BYTE_LENGTH + 16,
|
|
|
|
/**
|
|
* Count of triangles in this polygon, number of VEC3 elements.
|
|
* @type {number}
|
|
* @ignore
|
|
*/
|
|
TRIANGLE_COUNT_U32: BufferPrimitive.Layout.__BYTE_LENGTH + 20,
|
|
|
|
/**
|
|
* @type {number}
|
|
* @ignore
|
|
*/
|
|
__BYTE_LENGTH: BufferPrimitive.Layout.__BYTE_LENGTH + 24,
|
|
};
|
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
// LIFECYCLE
|
|
|
|
/**
|
|
* Copies data from source polygon to result. If the result polygon is not
|
|
* new (the last polygon in the collection) then source and result polygons
|
|
* must have the same vertex counts, hole counts, and triangle counts.
|
|
*
|
|
* @param {BufferPolygon} polygon
|
|
* @param {BufferPolygon} result
|
|
* @return {BufferPolygon}
|
|
* @override
|
|
*/
|
|
static clone(polygon, result) {
|
|
super.clone(polygon, result);
|
|
result.setPositions(polygon.getPositions());
|
|
result.setHoles(polygon.getHoles());
|
|
result.setTriangles(polygon.getTriangles());
|
|
return result;
|
|
}
|
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
// GEOMETRY
|
|
|
|
/**
|
|
* Offset in collection position array to first vertex in polygon, number
|
|
* of VEC3 elements.
|
|
*
|
|
* @type {number}
|
|
* @readonly
|
|
* @ignore
|
|
*/
|
|
get vertexOffset() {
|
|
return this._getUint32(BufferPolygon.Layout.POSITION_OFFSET_U32);
|
|
}
|
|
|
|
/**
|
|
* Count of positions (vertices) in this polygon, including both outer ring and
|
|
* internal rings (holes), number of VEC3 elements.
|
|
*
|
|
* @type {number}
|
|
* @readonly
|
|
*/
|
|
get vertexCount() {
|
|
return this._getUint32(BufferPolygon.Layout.POSITION_COUNT_U32);
|
|
}
|
|
|
|
/**
|
|
* Returns an array view of this polygon's vertex positions. If 'result'
|
|
* argument is given, vertex positions are written to that array and returned.
|
|
* Otherwise, returns an ArrayView on collection memory — changes to this array
|
|
* will not trigger render updates, which requires `.setPositions()`.
|
|
*
|
|
* @param {TypedArray} [result]
|
|
* return {TypedArray}
|
|
*/
|
|
getPositions(result) {
|
|
return this._getPositionsRange(0, this.vertexCount, result);
|
|
}
|
|
|
|
/** @param {TypedArray} positions */
|
|
setPositions(positions) {
|
|
const collection = this._collection;
|
|
const vertexOffset = this.vertexOffset;
|
|
const srcCount = this.vertexCount;
|
|
const dstCount = positions.length / 3;
|
|
const collectionCount = collection.vertexCount + dstCount - srcCount;
|
|
|
|
//>>includeStart('debug', pragmas.debug);
|
|
assert(srcCount === dstCount || this._isResizable(), ERR_RESIZE);
|
|
assert(collectionCount <= collection.vertexCountMax, ERR_CAPACITY);
|
|
//>>includeEnd('debug');
|
|
|
|
collection._positionCount = collectionCount;
|
|
this._setUint32(BufferPolygon.Layout.POSITION_COUNT_U32, dstCount);
|
|
|
|
const positionView = collection._positionView;
|
|
for (let i = 0; i < dstCount; i++) {
|
|
positionView[(vertexOffset + i) * 3] = positions[i * 3];
|
|
positionView[(vertexOffset + i) * 3 + 1] = positions[i * 3 + 1];
|
|
positionView[(vertexOffset + i) * 3 + 2] = positions[i * 3 + 2];
|
|
}
|
|
|
|
this._dirty = true;
|
|
collection._makeDirtyBoundingVolume();
|
|
}
|
|
|
|
/**
|
|
* Offset in collection position array to first vertex in polygon's outer
|
|
* linear ring, number of VEC3 elements.
|
|
*
|
|
* @type {number}
|
|
* @readonly
|
|
*/
|
|
get outerVertexOffset() {
|
|
return this.vertexOffset;
|
|
}
|
|
|
|
/**
|
|
* Count of positions (vertices) in this polygon's outer linear ring, number
|
|
* of VEC3 elements.
|
|
*
|
|
* @type {number}
|
|
* @readonly
|
|
*/
|
|
get outerVertexCount() {
|
|
if (this.holeCount > 0) {
|
|
return this.getHoles()[0];
|
|
}
|
|
return this.vertexCount;
|
|
}
|
|
|
|
/**
|
|
* Returns an array view of this polygon's outer linear ring vertex positions.
|
|
* If 'result' argument is given, vertex positions are written to that array
|
|
* and returned. Otherwise, returns an ArrayView on collection memory —
|
|
* changes to this array will not trigger render updates, which requires
|
|
* `.setPositions()`.
|
|
*
|
|
* @param {TypedArray} [result]
|
|
* @returns {TypedArray}
|
|
*/
|
|
getOuterPositions(result) {
|
|
return this._getPositionsRange(0, this.outerVertexCount, result);
|
|
}
|
|
|
|
/**
|
|
* Offset in collection holes array to first hole in polygon, number of
|
|
* integer elements.
|
|
*
|
|
* @type {number}
|
|
* @readonly
|
|
* @ignore
|
|
*/
|
|
get holeOffset() {
|
|
return this._getUint32(BufferPolygon.Layout.HOLE_OFFSET_U32);
|
|
}
|
|
|
|
/**
|
|
* Count of holes (indices) in this polygon.
|
|
*
|
|
* @type {number}
|
|
* @readonly
|
|
*/
|
|
get holeCount() {
|
|
return this._getUint32(BufferPolygon.Layout.HOLE_COUNT_U32);
|
|
}
|
|
|
|
/**
|
|
* Gets this polygon's hole indices, with each hole represented as a single
|
|
* offset into this polygon's positions array. Each hole implicitly
|
|
* continues along an internal linear ring from that vertex offset until
|
|
* reaching either the end of the positions array, or the next hole offset.
|
|
*
|
|
* If 'result' argument is given, hole indices are written to that array and
|
|
* returned. Otherwise, returns an ArrayView on collection memory — changes
|
|
* to this array will not trigger render updates, which requires `.setHoles()`.
|
|
*
|
|
* @param {TypedArray} [result]
|
|
* @returns {TypedArray}
|
|
*/
|
|
getHoles(result) {
|
|
const { holeOffset, holeCount } = this;
|
|
const holeIndexView = this._collection._holeIndexView;
|
|
|
|
if (!defined(result)) {
|
|
const byteOffset =
|
|
holeIndexView.byteOffset + holeOffset * holeIndexView.BYTES_PER_ELEMENT;
|
|
const TypedArray = /** @type {TypedArrayConstructor} */ (
|
|
holeIndexView.constructor
|
|
);
|
|
return new TypedArray(
|
|
/** @type {ArrayBuffer} */ (holeIndexView.buffer),
|
|
byteOffset,
|
|
holeCount,
|
|
);
|
|
}
|
|
|
|
for (let i = 0; i < holeCount; i++) {
|
|
result[i] = holeIndexView[holeOffset + i];
|
|
}
|
|
return result;
|
|
}
|
|
|
|
/**
|
|
* Sets this polygon's hole indices, with holes represented as a single
|
|
* offset into this polygon's positions array. Each hole implicitly
|
|
* continues along an internal linear ring from that vertex offset until
|
|
* reaching either the end of the positions array, or the next hole offset.
|
|
*
|
|
* @param {TypedArray} holes
|
|
*/
|
|
setHoles(holes) {
|
|
const collection = this._collection;
|
|
const holeOffset = this.holeOffset;
|
|
const srcCount = this.holeCount;
|
|
const dstCount = holes.length;
|
|
const collectionCount = collection.holeCount + dstCount - srcCount;
|
|
|
|
//>>includeStart('debug', pragmas.debug);
|
|
assert(srcCount === dstCount || this._isResizable(), ERR_RESIZE);
|
|
assert(collectionCount <= collection.holeCountMax, ERR_CAPACITY);
|
|
//>>includeEnd('debug');
|
|
|
|
collection._holeCount = collectionCount;
|
|
this._setUint32(BufferPolygon.Layout.HOLE_COUNT_U32, dstCount);
|
|
|
|
const holeIndexView = collection._holeIndexView;
|
|
for (let i = 0; i < dstCount; i++) {
|
|
holeIndexView[holeOffset + i] = holes[i];
|
|
}
|
|
|
|
this._dirty = true;
|
|
}
|
|
|
|
/**
|
|
* Returns the number of (VEC3) vertices in the specified hole.
|
|
*
|
|
* @param {number} holeIndex
|
|
* @returns {number}
|
|
*/
|
|
getHoleVertexCount(holeIndex) {
|
|
const holes = this.getHoles();
|
|
|
|
//>>includeStart('debug', pragmas.debug);
|
|
Check.typeOf.number.greaterThanOrEquals("holeIndex", holeIndex, 0);
|
|
Check.typeOf.number.lessThan("holeIndex", holeIndex, holes.length);
|
|
//>>includeEnd('debug');
|
|
|
|
const holeVertexOffset = holes[holeIndex];
|
|
return holeIndex === holes.length - 1
|
|
? this.vertexCount - holeVertexOffset
|
|
: holes[holeIndex + 1] - holeVertexOffset;
|
|
}
|
|
|
|
/**
|
|
* Returns an array view of the inner linear ring vertex positions for the
|
|
* specified hole. If 'result' argument is given, vertex positions are written
|
|
* to that array and returned. Otherwise, returns an ArrayView on collection
|
|
* memory — changes to this array will not trigger render updates, which
|
|
* requires `.setPositions()`.
|
|
*
|
|
* @param {number} holeIndex
|
|
* @param {TypedArray} [result]
|
|
* return {TypedArray}
|
|
*/
|
|
getHolePositions(holeIndex, result) {
|
|
const holes = this.getHoles();
|
|
|
|
//>>includeStart('debug', pragmas.debug);
|
|
Check.typeOf.number.greaterThanOrEquals("holeIndex", holeIndex, 0);
|
|
Check.typeOf.number.lessThan("holeIndex", holeIndex, holes.length);
|
|
//>>includeEnd('debug');
|
|
|
|
const holeVertexOffset = holes[holeIndex];
|
|
const holeVertexCount = this.getHoleVertexCount(holeIndex);
|
|
return this._getPositionsRange(holeVertexOffset, holeVertexCount, result);
|
|
}
|
|
|
|
/**
|
|
* Internal helper for accessing vertex positions. 'vertexOffset' argument
|
|
* is relative to the start of the polygon's vertex block, with 0 being
|
|
* the first vertex in the polygon. If 'result' argument is given, the
|
|
* requested range of vertices are written to the result array and returned.
|
|
* Otherwise, returns an ArrayView on collection memory.
|
|
*
|
|
* @param {number} vertexOffset
|
|
* @param {number} vertexCount
|
|
* @param {TypedArray} [result]
|
|
* @returns {TypedArray}
|
|
* @private
|
|
*/
|
|
_getPositionsRange(vertexOffset, vertexCount, result) {
|
|
const collection = this._collection;
|
|
const positionView = this._collection._positionView;
|
|
|
|
const collectionVertexOffset = this.vertexOffset + vertexOffset;
|
|
|
|
//>>includeStart('debug', pragmas.debug);
|
|
assert(collectionVertexOffset >= 0, ERR_OUT_OF_RANGE);
|
|
assert(collectionVertexOffset < collection.vertexCount, ERR_OUT_OF_RANGE);
|
|
assert(vertexCount > 0, ERR_OUT_OF_RANGE);
|
|
assert(vertexCount <= this.vertexCount, ERR_OUT_OF_RANGE);
|
|
//>>includeEnd('debug');
|
|
|
|
if (!defined(result)) {
|
|
const byteOffset =
|
|
positionView.byteOffset +
|
|
collectionVertexOffset * 3 * positionView.BYTES_PER_ELEMENT;
|
|
const TypedArray = /** @type {TypedArrayConstructor} */ (
|
|
positionView.constructor
|
|
);
|
|
return new TypedArray(
|
|
/** @type {ArrayBuffer} */ (positionView.buffer),
|
|
byteOffset,
|
|
vertexCount * 3,
|
|
);
|
|
}
|
|
|
|
for (let i = 0; i < vertexCount; i++) {
|
|
result[i * 3] = positionView[(collectionVertexOffset + i) * 3];
|
|
result[i * 3 + 1] = positionView[(collectionVertexOffset + i) * 3 + 1];
|
|
result[i * 3 + 2] = positionView[(collectionVertexOffset + i) * 3 + 2];
|
|
}
|
|
return result;
|
|
}
|
|
|
|
/**
|
|
* Offset in collection triangles array to first triangle in polygon,
|
|
* number of VEC3 elements.
|
|
* @type {number}
|
|
* @readonly
|
|
* @ignore
|
|
*/
|
|
get triangleOffset() {
|
|
return this._getUint32(BufferPolygon.Layout.TRIANGLE_OFFSET_U32);
|
|
}
|
|
|
|
/**
|
|
* Count of triangles in this polygon, number of VEC3 elements.
|
|
*
|
|
* @type {number}
|
|
* @readonly
|
|
*/
|
|
get triangleCount() {
|
|
return this._getUint32(BufferPolygon.Layout.TRIANGLE_COUNT_U32);
|
|
}
|
|
|
|
/**
|
|
* Returns an array view of this polygon's triangle indices, represented as
|
|
* three vertex indices per triangle.
|
|
*
|
|
* If 'result' argument is given, triangle indices are written to that array
|
|
* and returned. Otherwise, returns an ArrayView on collection memory —
|
|
* changes to this array will not trigger render updates, which requires
|
|
* `.setTriangles()`.
|
|
*
|
|
* @param {TypedArray} [result]
|
|
* @returns {TypedArray}
|
|
*/
|
|
getTriangles(result) {
|
|
const { triangleOffset, triangleCount } = this;
|
|
const indices = this._collection._triangleIndexView;
|
|
|
|
if (!defined(result)) {
|
|
const byteOffset =
|
|
indices.byteOffset + triangleOffset * 3 * indices.BYTES_PER_ELEMENT;
|
|
const TypedArray = /** @type {TypedArrayConstructor} */ (
|
|
indices.constructor
|
|
);
|
|
return new TypedArray(
|
|
/** @type {ArrayBuffer} */ (indices.buffer),
|
|
byteOffset,
|
|
triangleCount * 3,
|
|
);
|
|
}
|
|
|
|
for (let i = 0; i < triangleCount; i++) {
|
|
result[i * 3] = indices[(triangleOffset + i) * 3];
|
|
result[i * 3 + 1] = indices[(triangleOffset + i) * 3 + 1];
|
|
result[i * 3 + 2] = indices[(triangleOffset + i) * 3 + 2];
|
|
}
|
|
return result;
|
|
}
|
|
|
|
/**
|
|
* Sets this polygon's triangle indices, represented as three vertex indices
|
|
* per triangle.
|
|
*
|
|
* @param {TypedArray} indices
|
|
*/
|
|
setTriangles(indices) {
|
|
const collection = this._collection;
|
|
const triangleOffset = this.triangleOffset;
|
|
const srcCount = this.triangleCount;
|
|
const dstCount = indices.length / 3;
|
|
const collectionCount = collection.triangleCount + dstCount - srcCount;
|
|
|
|
//>>includeStart('debug', pragmas.debug);
|
|
assert(srcCount === dstCount || this._isResizable(), ERR_RESIZE);
|
|
assert(collectionCount <= collection.triangleCountMax, ERR_CAPACITY);
|
|
//>>includeEnd('debug');
|
|
|
|
collection._triangleCount += dstCount - srcCount;
|
|
this._setUint32(BufferPolygon.Layout.TRIANGLE_COUNT_U32, dstCount);
|
|
|
|
const dstIndices = collection._triangleIndexView;
|
|
for (let i = 0; i < dstCount; i++) {
|
|
dstIndices[(triangleOffset + i) * 3] = indices[i * 3];
|
|
dstIndices[(triangleOffset + i) * 3 + 1] = indices[i * 3 + 1];
|
|
dstIndices[(triangleOffset + i) * 3 + 2] = indices[i * 3 + 2];
|
|
}
|
|
|
|
this._dirty = true;
|
|
}
|
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
// DEBUG
|
|
|
|
/**
|
|
* Returns a JSON-serializable object representing the polygon. This encoding
|
|
* is not memory-efficient, and should generally be used for debugging and
|
|
* testing.
|
|
*
|
|
* @returns {Object} JSON-serializable object.
|
|
* @override
|
|
*/
|
|
toJSON() {
|
|
return {
|
|
...super.toJSON(),
|
|
positions: Array.from(this.getPositions()),
|
|
holes: Array.from(this.getHoles()),
|
|
triangles: Array.from(this.getTriangles()),
|
|
};
|
|
}
|
|
}
|
|
|
|
export default BufferPolygon;
|