Skip to content

Commit 5174861

Browse files
aidinabediwilleastcott
aidinabedi
and
willeastcott
authored
[DOCS] Document APIs related to vertex attributes (playcanvas#1898)
* move the type for parameter "description" (in VertexFormat constructor) into a separate interface VertexAttributeDescription * add interface VertexAttributeElement (which extends VertexAttributeDescription) with additional vertex buffer layout data. * use new interface VertexAttributeElement in property VertexFormat#elements * fix all referances to old VertexAttributeElement properties * document VertexIteratorAccessor and methods * fix type for property VertexIterator#element * Revert "fix all referances to old VertexAttributeElement properties" This reverts commit 40029b2. * Partial revert "use new interface VertexAttributeElement in property VertexFormat#elements" * Copy documentation from VertexAttributeDescription to VertexAttributeElement (but using different property names) * remove unecessary dot * add param to interface constructors * revert description param in VertexFormat ctor and remove VertexAttributeDescription * simplify VertexAttributeElement by removing ctor params * change jsdoc for VertexAttributeElement from interface to class * construct VertexAttributeElement instances in VertexFormat * Revert "construct VertexAttributeElement instances in VertexFormat" This reverts commit cac35e7. * remove VertexAttributeElement and document VertexFormat#elements and VertexIteratorAccessor ctor (param vertexElement) individually * document vertexFormat parameter in VertexIteratorAccessor constructor * document VertexIteratorAccessor#setFromArray * document VertexIteratorAccessor#getToArray Co-authored-by: Will Eastcott <will@playcanvas.com>
1 parent 3b9747b commit 5174861

File tree

2 files changed

+133
-2
lines changed

2 files changed

+133
-2
lines changed

‎src/graphics/vertex-format.js

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,45 @@ Object.assign(pc, function () {
5757
* number of vertices. (example: PPPPNNNNCCCC), where arrays of individual attributes will be stored one right after the other (subject to alignment requirements).
5858
* Note that in this case, the format depends on the number of vertices, and needs to change when the number of vertices changes.
5959
* When not specified, vertex format will be interleaved. (example: PNCPNCPNCPNC)
60+
* @property {object[]} elements The vertex attribute elements.
61+
* @property {string} elements[].name The meaning of the vertex element. This is used to link
62+
* the vertex data to a shader input. Can be:
63+
*
64+
* * {@link pc.SEMANTIC_POSITION}
65+
* * {@link pc.SEMANTIC_NORMAL}
66+
* * {@link pc.SEMANTIC_TANGENT}
67+
* * {@link pc.SEMANTIC_BLENDWEIGHT}
68+
* * {@link pc.SEMANTIC_BLENDINDICES}
69+
* * {@link pc.SEMANTIC_COLOR}
70+
* * {@link pc.SEMANTIC_TEXCOORD0}
71+
* * {@link pc.SEMANTIC_TEXCOORD1}
72+
* * {@link pc.SEMANTIC_TEXCOORD2}
73+
* * {@link pc.SEMANTIC_TEXCOORD3}
74+
* * {@link pc.SEMANTIC_TEXCOORD4}
75+
* * {@link pc.SEMANTIC_TEXCOORD5}
76+
* * {@link pc.SEMANTIC_TEXCOORD6}
77+
* * {@link pc.SEMANTIC_TEXCOORD7}
78+
*
79+
* If vertex data has a meaning other that one of those listed above, use the user-defined
80+
* semantics: pc.SEMANTIC_ATTR0 to pc.SEMANTIC_ATTR15.
81+
* @property {number} elements[].numComponents The number of components of the vertex attribute.
82+
* Can be 1, 2, 3 or 4.
83+
* @property {number} elements[].dataType The data type of the attribute. Can be:
84+
*
85+
* * {@link pc.TYPE_INT8}
86+
* * {@link pc.TYPE_UINT8}
87+
* * {@link pc.TYPE_INT16}
88+
* * {@link pc.TYPE_UINT16}
89+
* * {@link pc.TYPE_INT32}
90+
* * {@link pc.TYPE_UINT32}
91+
* * {@link pc.TYPE_FLOAT32}
92+
* @property {boolean} elements[].normalize If true, vertex attribute data will be mapped from a
93+
* 0 to 255 range down to 0 to 1 when fed to a shader. If false, vertex attribute data is left
94+
* unchanged. If this property is unspecified, false is assumed.
95+
* @property {number} elements[].offset The number of initial bytes at the start of a vertex that are not relevant to this attribute.
96+
* @property {number} elements[].stride The number of total bytes that are between the start of one vertex, and the start of the next.
97+
* @property {pc.ScopeId} elements[].scopeId The shader input variable corresponding to the attribute.
98+
* @property {number} elements[].size The size of the attribute in bytes.
6099
* @example
61100
* // Specify 3-component positions (x, y, z)
62101
* var vertexFormat = new pc.VertexFormat(graphicsDevice, [

‎src/graphics/vertex-iterator.js

Lines changed: 94 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,53 @@
11
Object.assign(pc, function () {
22
'use strict';
33

4+
/**
5+
* @class
6+
* @name pc.VertexIteratorAccessor
7+
* @classdesc Helps with accessing a specific vertex attribute.
8+
* @description Returns a new pc.VertexIteratorAccessor object.
9+
* @param {ArrayBuffer} buffer - The vertex buffer containing the attribute to be accessed.
10+
* @param {object} vertexElement - The vertex attribute to be accessed.
11+
* @param {string} vertexElement.name - The meaning of the vertex element. This is used to link
12+
* the vertex data to a shader input. Can be:
13+
*
14+
* * {@link pc.SEMANTIC_POSITION}
15+
* * {@link pc.SEMANTIC_NORMAL}
16+
* * {@link pc.SEMANTIC_TANGENT}
17+
* * {@link pc.SEMANTIC_BLENDWEIGHT}
18+
* * {@link pc.SEMANTIC_BLENDINDICES}
19+
* * {@link pc.SEMANTIC_COLOR}
20+
* * {@link pc.SEMANTIC_TEXCOORD0}
21+
* * {@link pc.SEMANTIC_TEXCOORD1}
22+
* * {@link pc.SEMANTIC_TEXCOORD2}
23+
* * {@link pc.SEMANTIC_TEXCOORD3}
24+
* * {@link pc.SEMANTIC_TEXCOORD4}
25+
* * {@link pc.SEMANTIC_TEXCOORD5}
26+
* * {@link pc.SEMANTIC_TEXCOORD6}
27+
* * {@link pc.SEMANTIC_TEXCOORD7}
28+
*
29+
* If vertex data has a meaning other that one of those listed above, use the user-defined
30+
* semantics: pc.SEMANTIC_ATTR0 to pc.SEMANTIC_ATTR15.
31+
* @param {number} vertexElement.numComponents - The number of components of the vertex attribute.
32+
* Can be 1, 2, 3 or 4.
33+
* @param {number} vertexElement.dataType - The data type of the attribute. Can be:
34+
*
35+
* * {@link pc.TYPE_INT8}
36+
* * {@link pc.TYPE_UINT8}
37+
* * {@link pc.TYPE_INT16}
38+
* * {@link pc.TYPE_UINT16}
39+
* * {@link pc.TYPE_INT32}
40+
* * {@link pc.TYPE_UINT32}
41+
* * {@link pc.TYPE_FLOAT32}
42+
* @param {boolean} vertexElement.normalize - If true, vertex attribute data will be mapped from a
43+
* 0 to 255 range down to 0 to 1 when fed to a shader. If false, vertex attribute data is left
44+
* unchanged. If this property is unspecified, false is assumed.
45+
* @param {number} vertexElement.offset - The number of initial bytes at the start of a vertex that are not relevant to this attribute.
46+
* @param {number} vertexElement.stride - The number of total bytes that are between the start of one vertex, and the start of the next.
47+
* @param {pc.ScopeId} vertexElement.scopeId - The shader input variable corresponding to the attribute.
48+
* @param {number} vertexElement.size - The size of the attribute in bytes.
49+
* @param {pc.VertexFormat} vertexFormat - A vertex format that defines the layout of vertex data inside the buffer.
50+
*/
451
function VertexIteratorAccessor(buffer, vertexElement, vertexFormat) {
552
this.index = 0;
653
this.numComponents = vertexElement.numComponents;
@@ -65,10 +112,30 @@ Object.assign(pc, function () {
65112
}
66113
}
67114

115+
/**
116+
* @function
117+
* @name pc.VertexIteratorAccessor#get
118+
* @description Get a attribute component at the iterator's current index.
119+
* @param {number} offset - The component offset. Should be either 0, 1, 2, or 3.
120+
* @returns {number} The value of a attribute component.
121+
*/
68122
VertexIteratorAccessor.prototype.get = function (offset) {
69123
return this.array[this.index + offset];
70124
};
71125

126+
/**
127+
* @function
128+
* @name pc.VertexIteratorAccessor#set
129+
* @description Set all the attribute components at the iterator's current index.
130+
* @param {number} a - The first component value.
131+
* @param {number} [b] - The second component value (if applicable).
132+
* @param {number} [c] - The third component value (if applicable).
133+
* @param {number} [d] - The fourth component value (if applicable).
134+
*/
135+
VertexIteratorAccessor.prototype.set = function (a, b, c, d) {
136+
// Will be replaced with specialized implementation based on number of components
137+
};
138+
72139
function VertexIteratorAccessor_set1(a) {
73140
this.array[this.index] = a;
74141
}
@@ -91,6 +158,18 @@ Object.assign(pc, function () {
91158
this.array[this.index + 3] = d;
92159
}
93160

161+
/**
162+
* @function
163+
* @name pc.VertexIteratorAccessor#setFromArray
164+
* @description Write attribute components from an input array.
165+
* @param {number} index - The starting index at which to write data into the buffer. Will be used instead of the iterator's current index.
166+
* @param {number[]|Int8Array|Uint8Array|Uint8ClampedArray|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array} inputArray - The input array to read data from.
167+
* @param {number} inputIndex - The input index at which to read from the input array.
168+
*/
169+
VertexIteratorAccessor.prototype.setFromArray = function (index, inputArray, inputIndex) {
170+
// Will be replaced with specialized implementation based on number of components
171+
};
172+
94173
function VertexIteratorAccessor_arraySet1(index, inputArray, inputIndex) {
95174
this.array[index] = inputArray[inputIndex];
96175
}
@@ -113,6 +192,18 @@ Object.assign(pc, function () {
113192
this.array[index + 3] = inputArray[inputIndex + 3];
114193
}
115194

195+
/**
196+
* @function
197+
* @name pc.VertexIteratorAccessor#getToArray
198+
* @description Read attribute components to an output array.
199+
* @param {number} offset - The component offset at which to read data from the buffer. Will be used instead of the iterator's current index.
200+
* @param {number[]|Int8Array|Uint8Array|Uint8ClampedArray|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array} outputArray - The output array to write data into.
201+
* @param {number} outputIndex - The output index at which to write into the output array.
202+
*/
203+
VertexIteratorAccessor.prototype.getToArray = function (offset, outputArray, outputIndex) {
204+
// Will be replaced with specialized implementation based on number of components
205+
};
206+
116207
function VertexIteratorAccessor_arrayGet1(offset, outputArray, outputIndex) {
117208
outputArray[outputIndex] = this.array[offset];
118209
}
@@ -140,8 +231,8 @@ Object.assign(pc, function () {
140231
* @name pc.VertexIterator
141232
* @classdesc A vertex iterator simplifies the process of writing vertex data to a vertex buffer.
142233
* @description Returns a new pc.VertexIterator object.
143-
* @param {pc.VertexBuffer} vertexBuffer - The vertex buffer to be iterated.
144-
* @property {object} element The vertex buffer elements.
234+
* @param {pc.VertexBuffer} vertexBuffer - The vertex buffer to be iterated.
235+
* @property {object<string, pc.VertexIteratorAccessor>} element The vertex buffer elements.
145236
*/
146237
function VertexIterator(vertexBuffer) {
147238
// Store the vertex buffer
@@ -304,6 +395,7 @@ Object.assign(pc, function () {
304395
});
305396

306397
return {
398+
VertexIteratorAccessor: VertexIteratorAccessor,
307399
VertexIterator: VertexIterator
308400
};
309401
}());

0 commit comments

Comments
 (0)