GeometryAttributes (object)¶
The GeometryAttributes object is a generic container that contains a named set of GeometryAttribute. Each GeometryAttribute is an array containing values of a specific type. For example, the “positions” attribute is typically a Vec3Attribute containing Vec3 elements.
All Geometry types, such as the PolygonMesh, contain a GeometryAttributes container which can be retrieved using the Geometry.getAttributes interface method. However, it is the geometry that controls the order and meaning of the attribute elements within the GeometryAttribute array. For example, the PolygonMesh maintains information about how the values are shared.
注釈
Attributes needs to be uniquely identified by a name. The GeometryAttributes cannot contain multiple attributes with the same name, even if the type differs.
Attribute versioning¶
In order to allow for optimal performance and multithreading, attributes contain a version number (UInt32) which has to be explicitly incremented after value modifications. However, if the size of the attribute array changes, the version will be automatically incremented. Attribute clients, such as InlineDrawing, can then detect value changes efficiently in order to update their state.
注釈
This versioning strategy favors performance over simplicity. Another choice could have been to automatically increase the version when detecting a value difference. Another could have been to let the clients compare values to their last state using a copy or a hash of the values. However, these would have caused performance overhead that could be relatively important in some situations.
Similarly, the GeometryAttributes.keysVersion member defines a version for the set of attributes, which will get incremented only if attributes get added or removed from the container, but not upon attribute resize or value changes.
Members¶
| UInt32 | keysVersion | Version of the attribute set. This is incremented only if attributes are added or removed, and not if values are changed or values array is resized. |
| UInt32 | attributesValueVersion | |
| Ref<GeometryAttribute> | positionsAttribute | Fast access to the positions attribute, if it exists. Note: might be Vec3Attribute or Vec3_dAttribute depending on the precision. |
| Ref<GeometryAttribute> | normalsAttribute | Fast access to normals attribute, if it exists. |
| String | debugName | Name to be used by descriptions |
/*
** Example: GeometryAttributes
*/
require Geometry;
function reportAttributes( Geometry geom ) {
// Get the attributes container from the geometry
Ref<GeometryAttributes> attributes = geom.getAttributes();
report('Number of attributes: ' + attributes.attributeCount());
report('Number of elements: ' + attributes.size());
// Iterate over the attributes
GeometryAttributesIterator iter = attributes.getAttributesIterator();
Ref<GeometryAttribute> attribute = null;
while( attribute = iter.getNext() )
report( 'Attribute ' + attribute.getName() + ' of type ' + attribute.type() );
}
operator entry() {
PolygonMesh p();
p.addSphere( Xfo(), 1.0, 3, true, true );
reportAttributes(p);
}
/*
** Output:
Number of attributes: 3
Number of elements: 77
Attribute positions of type Vec3Attribute
Attribute normals of type Vec3Attribute
Attribute uvs0 of type Vec2Attribute
*/
Methods¶
Methods in detail¶
GeometryAttributes ( in GeometryAttributes other )
copy constructor
GeometryAttributes.attachNewAttribute! ( in Ref<GeometryAttribute> attribute )
Attaches an un-owned attribute. The GeometryAttributes becomes the owner of this attribute.
注釈
For common attribute types, the GeometryAttributes.getOrCreate[Type]Attribute helpers should be used instead.
注釈
An error will be thrown if another attribute has the same name.
Size GeometryAttributes.attributeCount? ()
バージョン 1.13.0 で追加.
Returns the number of attributes (size of the attribute set).
注釈
This is different from the size of the attribute value array, which is GeometryAttributes.size
GeometryAttributes.clear! ()
Removes all attributes, and resets attribute value array sizes to 0.
GeometryAttributes GeometryAttributes.clone? ()
clone method
GeometryAttributes.cloneMembersTo? ( io GeometryAttributes that )
GeometryAttributes.copy! ( in Ref<GeometryAttributes> other )
Copies from another attribute container. This will increment GeometryAttributes.keysVersion only if the attribute set differs.
注釈
This can be more efficient than using .clone(), since it will reuse the same attribute buffer memory when possible.
GeometryAttributes.copyValue? ( in Size sourceIndex, in Size targetIndex )
For each contained attribute, sets the attribute value located at sourceIndex from the value located at targetIndex.
GeometryAttributes.copyValues! ( in Ref<GeometryAttributes> sourceAttributes, in Size sourceIndex, in Size count, in Size targetIndex, in Boolean createMissingSourceAttributes )
For each contained attribute, sets the attribute value located at sourceIndex from the value located at targetIndex.
| createMissingSourceAttributes | If a source attribute doesn’t exist on this container, create it. |
Ref<GeometryAttribute> GeometryAttributes.getAttribute? ( in String name )
Returns a contained attribute from its name, or ‘null’ if not found.
Ref<GeometryAttribute> GeometryAttributes.getAttribute? ( in String name, in Type expectedAttributeType )
Returns a contained attribute of a specific type from its name, or ‘null’ if not found or another type.
String GeometryAttributes.getAttributeListDesc? ()
Returns the list of contained attributes, without the values.
GeometryAttributesIterator GeometryAttributes.getAttributesIterator? ()
Returns an iterator for enumerating attributes part of the GeometryAttributes.
注釈
The enumeration order is unspecified.
String GeometryAttributes.getDesc? ( in Boolean useUnitTestPrint )
Returns a string description of all contained attribute values.
| useUnitTestPrint | If true, returns a numerically stable version which is unit test output friendly. |
String GeometryAttributes.getDesc? ()
Returns a string description of all contained attribute values.
Ref<Vec3Attribute> GeometryAttributes.getNormals? ()
Returns the normals attribute, or ‘null’ if it doesn’t exist.
Ref<GeometryAttribute> GeometryAttributes.getOrCreateAttribute! ( in String name, in Type attributeType )
Returns an attribute of a given name and type if it exists, else it creates and returns it.
注釈
This function is legacy, and is kept for backward compatibility. In particular, it only supports a finite set of built-in types. GeometryAttributes.getOrCreate[Type]Attribute helper functions should be used instead.
Ref<ColorAttribute> GeometryAttributes.getOrCreateColorAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<IntegerAttribute> GeometryAttributes.getOrCreateIntegerAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<Mat33Attribute> GeometryAttributes.getOrCreateMat33Attribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<Mat44Attribute> GeometryAttributes.getOrCreateMat44Attribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<Vec3Attribute> GeometryAttributes.getOrCreateNormals! ()
Returns the normals attribute, and creates it if it doesn’t exist.
Ref<Vec3Attribute> GeometryAttributes.getOrCreatePositions! ()
Returns the positions attribute (Float32) if it exists, else it creates it. If positions already exist as Float64, an exception is raised.
Ref<Vec3_dAttribute> GeometryAttributes.getOrCreatePositions_d! ()
Returns the positions attribute (Float64) if it exists, else it creates it. If positions already exist as Float32, an exception is raised.
Ref<QuatAttribute> GeometryAttributes.getOrCreateQuatAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<RGBAAttribute> GeometryAttributes.getOrCreateRGBAAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<RGBAttribute> GeometryAttributes.getOrCreateRGBAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<ScalarAttribute> GeometryAttributes.getOrCreateScalarAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<ScalarConstantArrayAttribute> GeometryAttributes.getOrCreateScalarConstantArrayAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<SkinningAttribute> GeometryAttributes.getOrCreateSkinningAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<UInt16ConstantArrayAttribute> GeometryAttributes.getOrCreateUInt16ConstantArrayAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<UInt32Attribute> GeometryAttributes.getOrCreateUInt32Attribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<Vec2Attribute> GeometryAttributes.getOrCreateVec2Attribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<Vec3Attribute> GeometryAttributes.getOrCreateVec3Attribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<Vec3_dAttribute> GeometryAttributes.getOrCreateVec3_dAttribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Ref<Vec4Attribute> GeometryAttributes.getOrCreateVec4Attribute! ( in String name )
If it exists, returns the attribute of that name, else creates it.
Vec3 GeometryAttributes.getPosition? ( in Size index )
Returns the position at the given index. A conversion is made if stored as Float64.
注釈
This function is less efficient than calling getPositions() and then working directly with values.
Vec3_d GeometryAttributes.getPosition_d? ( in Size index )
Returns the position at the given index. A conversion is made if stored as Float32.
注釈
This function is less efficient than calling getPositions_d() and then working directly with values.
Ref<Vec3Attribute> GeometryAttributes.getPositions? ()
Returns the positions attribute (Float32) if exists, else ‘null’
Ref<Vec3_dAttribute> GeometryAttributes.getPositions_d? ()
Returns the positions attribute (Float64) if exists, else ‘null’
Boolean GeometryAttributes.has? ( in String name )
Returns true if an attribute of a given name exists.
Boolean GeometryAttributes.has? ( in String name, in Type attributeType )
Returns true if it an attribute of a given name and type exists.
Boolean GeometryAttributes.hasFloat64Positions? ()
Returns true if positions are stored as Float64 (double precision), else they are stored as Float32.
GeometryAttributes.incrementAttributesValueVersion! ()
GeometryAttributes.linearCombine? ( in LocalL16UInt32Array sourceIndices, in LocalL16ScalarArray sourceWeights, in Size targetIndex )
For each contained attribute, sets the value located at targetIndex as a linear combination of source values.
| sourceIndices | The array of source indices |
| sourceWeights | The array of source weights, which need to correspond to each sourceIndices. Normally the sum of the weights should be 1.0 |
| targetIndex | The target value index |
GeometryAttributes.removeAttribute! ( in String name )
Removes the attribute that has this name.
GeometryAttributes.resize! ( in Size newCount )
Resizes the value array of all contained attributes.
注釈
If this GeometryAttributes is owned by a Geometry, only the Geometry should call this method.
GeometryAttributes.setPosition? ( in Size index, in Vec3 pos )
Sets the position for the given index. A conversion is made if stored as Float64.
注釈
This function is less efficient than calling getPositions() and then working directly with values.
GeometryAttributes.setPosition? ( in Size index, in Vec3_d pos )
Sets the position for the given index. A conversion is made if stored as Float32.
注釈
This function is less efficient than calling getPositions() and then working directly with values.
Size GeometryAttributes.size? ()
Returns the size of the attribute value array for any contained GeometryAttribute (they all have the same size).
注釈
This is different from the number of attribute (attribute set size), which is GeometryAttributes.attributeCount
