import Cartesian2 from "../Core/Cartesian2.js";
import Cartesian3 from "../Core/Cartesian3.js";
import Cartesian4 from "../Core/Cartesian4.js";
import combine from "../Core/combine.js";
import ComponentDatatype from "../Core/ComponentDatatype.js";
import defined from "../Core/defined.js";
import destroyObject from "../Core/destroyObject.js";
import DeveloperError from "../Core/DeveloperError.js";
import PixelFormat from "../Core/PixelFormat.js";
import ContextLimits from "../Renderer/ContextLimits.js";
import PixelDatatype from "../Renderer/PixelDatatype.js";
import Sampler from "../Renderer/Sampler.js";
import Texture from "../Renderer/Texture.js";
/**
* Creates a texture to look up per instance attributes for batched primitives. For example, store each primitive's pick color in the texture.
*
* @alias BatchTable
* @constructor
* @private
*
* @param {Context} context The context in which the batch table is created.
* @param {Object[]} attributes An array of objects describing a per instance attribute. Each object contains a datatype, components per attributes, whether it is normalized and a function name
* to retrieve the value in the vertex shader.
* @param {Number} numberOfInstances The number of instances in a batch table.
*
* @example
* // create the batch table
* var attributes = [{
* functionName : 'getShow',
* componentDatatype : ComponentDatatype.UNSIGNED_BYTE,
* componentsPerAttribute : 1
* }, {
* functionName : 'getPickColor',
* componentDatatype : ComponentDatatype.UNSIGNED_BYTE,
* componentsPerAttribute : 4,
* normalize : true
* }];
* var batchTable = new BatchTable(context, attributes, 5);
*
* // when creating the draw commands, update the uniform map and the vertex shader
* vertexShaderSource = batchTable.getVertexShaderCallback()(vertexShaderSource);
* var shaderProgram = ShaderProgram.fromCache({
* // ...
* vertexShaderSource : vertexShaderSource,
* });
*
* drawCommand.shaderProgram = shaderProgram;
* drawCommand.uniformMap = batchTable.getUniformMapCallback()(uniformMap);
*
* // use the attribute function names in the shader to retrieve the instance values
* // ...
* attribute float batchId;
*
* void main() {
* // ...
* float show = getShow(batchId);
* vec3 pickColor = getPickColor(batchId);
* // ...
* }
*/
function BatchTable(context, attributes, numberOfInstances) {
//>>includeStart('debug', pragmas.debug);
if (!defined(context)) {
throw new DeveloperError("context is required");
}
if (!defined(attributes)) {
throw new DeveloperError("attributes is required");
}
if (!defined(numberOfInstances)) {
throw new DeveloperError("numberOfInstances is required");
}
//>>includeEnd('debug');
this._attributes = attributes;
this._numberOfInstances = numberOfInstances;
if (attributes.length === 0) {
return;
}
// PERFORMANCE_IDEA: We may be able to arrange the attributes so they can be packing into fewer texels.
// Right now, an attribute with one component uses an entire texel when 4 single component attributes can
// be packed into a texel.
//
// Packing floats into unsigned byte textures makes the problem worse. A single component float attribute
// will be packed into a single texel leaving 3 texels unused. 4 texels are reserved for each float attribute
// regardless of how many components it has.
var pixelDatatype = getDatatype(attributes);
var textureFloatSupported = context.floatingPointTexture;
var packFloats =
pixelDatatype === PixelDatatype.FLOAT && !textureFloatSupported;
var offsets = createOffsets(attributes, packFloats);
var stride = getStride(offsets, attributes, packFloats);
var maxNumberOfInstancesPerRow = Math.floor(
ContextLimits.maximumTextureSize / stride
);
var instancesPerWidth = Math.min(
numberOfInstances,
maxNumberOfInstancesPerRow
);
var width = stride * instancesPerWidth;
var height = Math.ceil(numberOfInstances / instancesPerWidth);
var stepX = 1.0 / width;
var centerX = stepX * 0.5;
var stepY = 1.0 / height;
var centerY = stepY * 0.5;
this._textureDimensions = new Cartesian2(width, height);
this._textureStep = new Cartesian4(stepX, centerX, stepY, centerY);
this._pixelDatatype = !packFloats
? pixelDatatype
: PixelDatatype.UNSIGNED_BYTE;
this._packFloats = packFloats;
this._offsets = offsets;
this._stride = stride;
this._texture = undefined;
var batchLength = 4 * width * height;
this._batchValues =
pixelDatatype === PixelDatatype.FLOAT && !packFloats
? new Float32Array(batchLength)
: new Uint8Array(batchLength);
this._batchValuesDirty = false;
}
Object.defineProperties(BatchTable.prototype, {
/**
* The attribute descriptions.
* @memberOf BatchTable.prototype
* @type {Object[]}
* @readonly
*/
attributes: {
get: function () {
return this._attributes;
},
},
/**
* The number of instances.
* @memberOf BatchTable.prototype
* @type {Number}
* @readonly
*/
numberOfInstances: {
get: function () {
return this._numberOfInstances;
},
},
});
function getDatatype(attributes) {
var foundFloatDatatype = false;
var length = attributes.length;
for (var i = 0; i < length; ++i) {
if (attributes[i].componentDatatype !== ComponentDatatype.UNSIGNED_BYTE) {
foundFloatDatatype = true;
break;
}
}
return foundFloatDatatype ? PixelDatatype.FLOAT : PixelDatatype.UNSIGNED_BYTE;
}
function getAttributeType(attributes, attributeIndex) {
var componentsPerAttribute =
attributes[attributeIndex].componentsPerAttribute;
if (componentsPerAttribute === 2) {
return Cartesian2;
} else if (componentsPerAttribute === 3) {
return Cartesian3;
} else if (componentsPerAttribute === 4) {
return Cartesian4;
}
return Number;
}
function createOffsets(attributes, packFloats) {
var offsets = new Array(attributes.length);
var currentOffset = 0;
var attributesLength = attributes.length;
for (var i = 0; i < attributesLength; ++i) {
var attribute = attributes[i];
var componentDatatype = attribute.componentDatatype;
offsets[i] = currentOffset;
if (componentDatatype !== ComponentDatatype.UNSIGNED_BYTE && packFloats) {
currentOffset += 4;
} else {
++currentOffset;
}
}
return offsets;
}
function getStride(offsets, attributes, packFloats) {
var length = offsets.length;
var lastOffset = offsets[length - 1];
var lastAttribute = attributes[length - 1];
var componentDatatype = lastAttribute.componentDatatype;
if (componentDatatype !== ComponentDatatype.UNSIGNED_BYTE && packFloats) {
return lastOffset + 4;
}
return lastOffset + 1;
}
var scratchPackedFloatCartesian4 = new Cartesian4();
function getPackedFloat(array, index, result) {
var packed = Cartesian4.unpack(array, index, scratchPackedFloatCartesian4);
var x = Cartesian4.unpackFloat(packed);
packed = Cartesian4.unpack(array, index + 4, scratchPackedFloatCartesian4);
var y = Cartesian4.unpackFloat(packed);
packed = Cartesian4.unpack(array, index + 8, scratchPackedFloatCartesian4);
var z = Cartesian4.unpackFloat(packed);
packed = Cartesian4.unpack(array, index + 12, scratchPackedFloatCartesian4);
var w = Cartesian4.unpackFloat(packed);
return Cartesian4.fromElements(x, y, z, w, result);
}
function setPackedAttribute(value, array, index) {
var packed = Cartesian4.packFloat(value.x, scratchPackedFloatCartesian4);
Cartesian4.pack(packed, array, index);
packed = Cartesian4.packFloat(value.y, packed);
Cartesian4.pack(packed, array, index + 4);
packed = Cartesian4.packFloat(value.z, packed);
Cartesian4.pack(packed, array, index + 8);
packed = Cartesian4.packFloat(value.w, packed);
Cartesian4.pack(packed, array, index + 12);
}
var scratchGetAttributeCartesian4 = new Cartesian4();
/**
* Gets the value of an attribute in the table.
*
* @param {Number} instanceIndex The index of the instance.
* @param {Number} attributeIndex The index of the attribute.
* @param {undefined|Cartesian2|Cartesian3|Cartesian4} [result] The object onto which to store the result. The type is dependent on the attribute's number of components.
* @returns {Number|Cartesian2|Cartesian3|Cartesian4} The attribute value stored for the instance.
*
* @exception {DeveloperError} instanceIndex is out of range.
* @exception {DeveloperError} attributeIndex is out of range.
*/
BatchTable.prototype.getBatchedAttribute = function (
instanceIndex,
attributeIndex,
result
) {
//>>includeStart('debug', pragmas.debug);
if (instanceIndex < 0 || instanceIndex >= this._numberOfInstances) {
throw new DeveloperError("instanceIndex is out of range.");
}
if (attributeIndex < 0 || attributeIndex >= this._attributes.length) {
throw new DeveloperError("attributeIndex is out of range");
}
//>>includeEnd('debug');
var attributes = this._attributes;
var offset = this._offsets[attributeIndex];
var stride = this._stride;
var index = 4 * stride * instanceIndex + 4 * offset;
var value;
if (
this._packFloats &&
attributes[attributeIndex].componentDatatype !== PixelDatatype.UNSIGNED_BYTE
) {
value = getPackedFloat(
this._batchValues,
index,
scratchGetAttributeCartesian4
);
} else {
value = Cartesian4.unpack(
this._batchValues,
index,
scratchGetAttributeCartesian4
);
}
var attributeType = getAttributeType(attributes, attributeIndex);
if (defined(attributeType.fromCartesian4)) {
return attributeType.fromCartesian4(value, result);
} else if (defined(attributeType.clone)) {
return attributeType.clone(value, result);
}
return value.x;
};
var setAttributeScratchValues = [
undefined,
undefined,
new Cartesian2(),
new Cartesian3(),
new Cartesian4(),
];
var setAttributeScratchCartesian4 = new Cartesian4();
/**
* Sets the value of an attribute in the table.
*
* @param {Number} instanceIndex The index of the instance.
* @param {Number} attributeIndex The index of the attribute.
* @param {Number|Cartesian2|Cartesian3|Cartesian4} value The value to be stored in the table. The type of value will depend on the number of components of the attribute.
*
* @exception {DeveloperError} instanceIndex is out of range.
* @exception {DeveloperError} attributeIndex is out of range.
*/
BatchTable.prototype.setBatchedAttribute = function (
instanceIndex,
attributeIndex,
value
) {
//>>includeStart('debug', pragmas.debug);
if (instanceIndex < 0 || instanceIndex >= this._numberOfInstances) {
throw new DeveloperError("instanceIndex is out of range.");
}
if (attributeIndex < 0 || attributeIndex >= this._attributes.length) {
throw new DeveloperError("attributeIndex is out of range");
}
if (!defined(value)) {
throw new DeveloperError("value is required.");
}
//>>includeEnd('debug');
var attributes = this._attributes;
var result =
setAttributeScratchValues[
attributes[attributeIndex].componentsPerAttribute
];
var currentAttribute = this.getBatchedAttribute(
instanceIndex,
attributeIndex,
result
);
var attributeType = getAttributeType(this._attributes, attributeIndex);
var entriesEqual = defined(attributeType.equals)
? attributeType.equals(currentAttribute, value)
: currentAttribute === value;
if (entriesEqual) {
return;
}
var attributeValue = setAttributeScratchCartesian4;
attributeValue.x = defined(value.x) ? value.x : value;
attributeValue.y = defined(value.y) ? value.y : 0.0;
attributeValue.z = defined(value.z) ? value.z : 0.0;
attributeValue.w = defined(value.w) ? value.w : 0.0;
var offset = this._offsets[attributeIndex];
var stride = this._stride;
var index = 4 * stride * instanceIndex + 4 * offset;
if (
this._packFloats &&
attributes[attributeIndex].componentDatatype !== PixelDatatype.UNSIGNED_BYTE
) {
setPackedAttribute(attributeValue, this._batchValues, index);
} else {
Cartesian4.pack(attributeValue, this._batchValues, index);
}
this._batchValuesDirty = true;
};
function createTexture(batchTable, context) {
var dimensions = batchTable._textureDimensions;
batchTable._texture = new Texture({
context: context,
pixelFormat: PixelFormat.RGBA,
pixelDatatype: batchTable._pixelDatatype,
width: dimensions.x,
height: dimensions.y,
sampler: Sampler.NEAREST,
flipY: false,
});
}
function updateTexture(batchTable) {
var dimensions = batchTable._textureDimensions;
batchTable._texture.copyFrom({
width: dimensions.x,
height: dimensions.y,
arrayBufferView: batchTable._batchValues,
});
}
/**
* Creates/updates the batch table texture.
* @param {FrameState} frameState The frame state.
*
* @exception {RuntimeError} The floating point texture extension is required but not supported.
*/
BatchTable.prototype.update = function (frameState) {
if (
(defined(this._texture) && !this._batchValuesDirty) ||
this._attributes.length === 0
) {
return;
}
this._batchValuesDirty = false;
if (!defined(this._texture)) {
createTexture(this, frameState.context);
}
updateTexture(this);
};
/**
* Gets a function that will update a uniform map to contain values for looking up values in the batch table.
*
* @returns {BatchTable.updateUniformMapCallback} A callback for updating uniform maps.
*/
BatchTable.prototype.getUniformMapCallback = function () {
var that = this;
return function (uniformMap) {
if (that._attributes.length === 0) {
return uniformMap;
}
var batchUniformMap = {
batchTexture: function () {
return that._texture;
},
batchTextureDimensions: function () {
return that._textureDimensions;
},
batchTextureStep: function () {
return that._textureStep;
},
};
return combine(uniformMap, batchUniformMap);
};
};
function getGlslComputeSt(batchTable) {
var stride = batchTable._stride;
// GLSL batchId is zero-based: [0, numberOfInstances - 1]
if (batchTable._textureDimensions.y === 1) {
return (
"uniform vec4 batchTextureStep; \n" +
"vec2 computeSt(float batchId) \n" +
"{ \n" +
" float stepX = batchTextureStep.x; \n" +
" float centerX = batchTextureStep.y; \n" +
" float numberOfAttributes = float(" +
stride +
"); \n" +
" return vec2(centerX + (batchId * numberOfAttributes * stepX), 0.5); \n" +
"} \n"
);
}
return (
"uniform vec4 batchTextureStep; \n" +
"uniform vec2 batchTextureDimensions; \n" +
"vec2 computeSt(float batchId) \n" +
"{ \n" +
" float stepX = batchTextureStep.x; \n" +
" float centerX = batchTextureStep.y; \n" +
" float stepY = batchTextureStep.z; \n" +
" float centerY = batchTextureStep.w; \n" +
" float numberOfAttributes = float(" +
stride +
"); \n" +
" float xId = mod(batchId * numberOfAttributes, batchTextureDimensions.x); \n" +
" float yId = floor(batchId * numberOfAttributes / batchTextureDimensions.x); \n" +
" return vec2(centerX + (xId * stepX), centerY + (yId * stepY)); \n" +
"} \n"
);
}
function getComponentType(componentsPerAttribute) {
if (componentsPerAttribute === 1) {
return "float";
}
return "vec" + componentsPerAttribute;
}
function getComponentSwizzle(componentsPerAttribute) {
if (componentsPerAttribute === 1) {
return ".x";
} else if (componentsPerAttribute === 2) {
return ".xy";
} else if (componentsPerAttribute === 3) {
return ".xyz";
}
return "";
}
function getGlslAttributeFunction(batchTable, attributeIndex) {
var attributes = batchTable._attributes;
var attribute = attributes[attributeIndex];
var componentsPerAttribute = attribute.componentsPerAttribute;
var functionName = attribute.functionName;
var functionReturnType = getComponentType(componentsPerAttribute);
var functionReturnValue = getComponentSwizzle(componentsPerAttribute);
var offset = batchTable._offsets[attributeIndex];
var glslFunction =
functionReturnType +
" " +
functionName +
"(float batchId) \n" +
"{ \n" +
" vec2 st = computeSt(batchId); \n" +
" st.x += batchTextureStep.x * float(" +
offset +
"); \n";
if (
batchTable._packFloats &&
attribute.componentDatatype !== PixelDatatype.UNSIGNED_BYTE
) {
glslFunction +=
"vec4 textureValue; \n" +
"textureValue.x = czm_unpackFloat(texture2D(batchTexture, st)); \n" +
"textureValue.y = czm_unpackFloat(texture2D(batchTexture, st + vec2(batchTextureStep.x, 0.0))); \n" +
"textureValue.z = czm_unpackFloat(texture2D(batchTexture, st + vec2(batchTextureStep.x * 2.0, 0.0))); \n" +
"textureValue.w = czm_unpackFloat(texture2D(batchTexture, st + vec2(batchTextureStep.x * 3.0, 0.0))); \n";
} else {
glslFunction += " vec4 textureValue = texture2D(batchTexture, st); \n";
}
glslFunction +=
" " +
functionReturnType +
" value = textureValue" +
functionReturnValue +
"; \n";
if (
batchTable._pixelDatatype === PixelDatatype.UNSIGNED_BYTE &&
attribute.componentDatatype === ComponentDatatype.UNSIGNED_BYTE &&
!attribute.normalize
) {
glslFunction += "value *= 255.0; \n";
} else if (
batchTable._pixelDatatype === PixelDatatype.FLOAT &&
attribute.componentDatatype === ComponentDatatype.UNSIGNED_BYTE &&
attribute.normalize
) {
glslFunction += "value /= 255.0; \n";
}
glslFunction += " return value; \n" + "} \n";
return glslFunction;
}
/**
* Gets a function that will update a vertex shader to contain functions for looking up values in the batch table.
*
* @returns {BatchTable.updateVertexShaderSourceCallback} A callback for updating a vertex shader source.
*/
BatchTable.prototype.getVertexShaderCallback = function () {
var attributes = this._attributes;
if (attributes.length === 0) {
return function (source) {
return source;
};
}
var batchTableShader = "uniform highp sampler2D batchTexture; \n";
batchTableShader += getGlslComputeSt(this) + "\n";
var length = attributes.length;
for (var i = 0; i < length; ++i) {
batchTableShader += getGlslAttributeFunction(this, i);
}
return function (source) {
var mainIndex = source.indexOf("void main");
var beforeMain = source.substring(0, mainIndex);
var afterMain = source.substring(mainIndex);
return beforeMain + "\n" + batchTableShader + "\n" + afterMain;
};
};
/**
* Returns true if this object was destroyed; otherwise, false.
* <br /><br />
* If this object was destroyed, it should not be used; calling any function other than
* <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
*
* @returns {Boolean} <code>true</code> if this object was destroyed; otherwise, <code>false</code>.
*
* @see BatchTable#destroy
*/
BatchTable.prototype.isDestroyed = function () {
return false;
};
/**
* Destroys the WebGL resources held by this object. Destroying an object allows for deterministic
* release of WebGL resources, instead of relying on the garbage collector to destroy this object.
* <br /><br />
* Once an object is destroyed, it should not be used; calling any function other than
* <code>isDestroyed</code> will result in a {@link DeveloperError} exception. Therefore,
* assign the return value (<code>undefined</code>) to the object as done in the example.
*
* @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
*
* @see BatchTable#isDestroyed
*/
BatchTable.prototype.destroy = function () {
this._texture = this._texture && this._texture.destroy();
return destroyObject(this);
};
/**
* A callback for updating uniform maps.
* @callback BatchTable.updateUniformMapCallback
*
* @param {Object} uniformMap The uniform map.
* @returns {Object} The new uniform map with properties for retrieving values from the batch table.
*/
/**
* A callback for updating a vertex shader source.
* @callback BatchTable.updateVertexShaderSourceCallback
*
* @param {String} vertexShaderSource The vertex shader source.
* @returns {String} The new vertex shader source with the functions for retrieving batch table values injected.
*/
export default BatchTable;
