Attributes¶
Attributes are containers for data associated with a GeoInfo
in NUKE. NUKE
allows for per-point, per-vertex, per-primitive, and per-object attributes.
These are described in the Attribute Groups section. Attributes can also
hold different types of value. For more information see the
Attribute Types section.
Although attributes belong to individual GeoInfo
objects, they are stored
as part of a GeometryList
so that they are packed and accessed more
efficiently.
Attribute Groups¶
There are six attribute groups in NUKE’s 3D system:
- Primitives
The shapes that make up the object. These can be triangles, individual points, polygons, and so on.
- Vertices
A point on a primitive. Vertices aren’t shared between primitives, but they don’t store a position directly - instead they have an index in the points list. So primitives cannot share a vertex, but they can each have a vertex that exists at the same point in space.
- Points
Coordinates of points in 3D space, usually stored in the object’s local coordinate system.
- Object
A single 3D object.
- Matrix
The transformation matrix from the object’s local coordinate system, to the world coordinate system.
- Attributes
Any other data associated with the object. Attributes themselves are associated with one of the other groups, which determines the cardinality of the attribute. To put it another way, a point attribute has one item per point; a vertex attribute has one item per vertex; and an object attribute only ever have one item.
These groups are defined by an enum in GeoInfo.h
:
enum GroupType {
Group_None = -1,
//
Group_Primitives = 0,
Group_Vertices = 1,
Group_Points = 2,
Group_Object = 3,
//
Group_Matrix = 4,
Group_Attributes = 5,
//
Group_Last = 6
};
The special value Group_None
is used to indicate an unknown or invalid
group; Group_Last
is always the total number of groups and is useful
for defining array sizes or when iterating over all groups (for example).
There’s also a set of bitmasks defined for the groups. These are mainly used
for the rebuild flags on the object and are defined in GeoInfo.h
, like
this:
enum {
Mask_No_Geometry = 0x00000000,
Mask_Primitives = 0x00000001, //!< Primitive list
Mask_Vertices = 0x00000002, //!< Vertex group
Mask_Points = 0x00000004, //!< Point list
Mask_Geometry = Mask_Primitives | Mask_Vertices | Mask_Points,
//
Mask_Object = 0x00000008, //!< The Object
Mask_Matrix = 0x00000010, //!< Local->World Transform Matrix
Mask_Attributes = 0x00000020, //!< Attribute list
//
Mask_All_Geometry = Mask_Geometry | Mask_Attributes | Mask_Object | Mask_Matrix,
};
typedef unsigned GeometryMask;
Note that some of the flags are just combinations of others, defined for
convenience: Mask_Geometry
and Mask_All_Geometry
.
Attribute Types¶
These are the attribute types NUKE recognizes:
- Float
A single floating point value.
- Vector2
A pair of floats.
- Vector3
Three floats.
- Vector4
Four floats.
- Normal
Three floats, like a Vector3, but transformed differently.
- Int
A single integer value.
- String
A
char*
value. You have to manage the memory that it points to yourself.- Pointer
A
void*
value. You can use this to store a pointer to any data you like; NUKE never tries to do anything with these other than passing them along the Node Graph (DAG) for you. This means you have to manage the memory that it points to yourself.- Matrix3
A 3x3 matrix, 9 floats altogether.
- Matrix4
A 4x4 matrix, 16 floats altogether.
There’s an enumeration defining these types in DDImage/Attribute.h
:
/*! Attribute data type enumerations. */
enum AttribType {
INVALID_ATTRIB = -1, //!< Data type not set
FLOAT_ATTRIB, //!< 1 float
VECTOR2_ATTRIB, //!< Vector2(2 floats)
VECTOR3_ATTRIB, //!< Vector3(3 floats)
VECTOR4_ATTRIB, //!< Vector4(4 floats)
NORMAL_ATTRIB, //!< Normal vector - Vector3(3 floats)
INT_ATTRIB, //!< Int
STRING_ATTRIB, //!< Char*
POINTER_ATTRIB, //!< Void*
MATRIX3_ATTRIB, //!< Matrix3 (9 floats)
MATRIX4_ATTRIB //!< Matrix4 (16 floats)
};
Attribute Contexts¶
An Attribute
object in the NDK is merely a data store: it contains the type
and number of values it holds, its name, and nothing else. It doesn’t have any
information about its wider context, such as the attribute group it belongs to.
DDImage provides the AttribContext
class to handle this.
An AttribContext
contains an Attribute
, a group type (e.g.
Group_Points
, Group_Vertices
), and additional information about how the
attribute is processed, such as whether it is interpolated or not.
Finding Out What Attributes are Available¶
The GeoInfo
class has two methods to help find out what attributes it has:
-
int
GeoInfo
::
get_attribcontext_count
() const¶ Get the number of attributes (and hence the number of
AttributeContext
objects) on thisGeoInfo
.
-
const AttribContext *
GeoInfo
::
get_attribcontext
(int index) const¶ Get an
AttribContext
using its list position rather than its name, type, and group.
Using these you can iterate over all the available attributes for a GeoInfo.
Getting Attributes¶
The GeoInfo
class provides read-only access to all of its attributes via
various lookup methods, as detailed below. Some of these methods allow you to
specify a group for the attribute; others do not. For the methods where you don’t
specify a group it searchs through a number of the groups in the following
order:
Group_Vertices
Group_Points
Group_Primitives
Group_Object
The GeoInfo
class provides the following methods for getting an
Attribute
:
-
const Attribute *
GeoInfo
::
get_attribute
(const char *name) const¶ Returns an
Attribute
with the specified name and any type, using the search order above.
-
const Attribute *
GeoInfo
::
get_typed_attribute
(const char *name, int type) const¶ Returns any
Attribute
with the specified name and type, using the search order above. If there is an attribute with a matching name but a different type, this returnsNULL
.
-
const Attribute *
GeoInfo
::
get_group_attribute
(int group, const char *name) const¶ Returns an
Attribute
, if one exists, with the specified name and any type. This only looks in the specified group and returnsNULL
if it doesn’t find one.
-
const Attribute *
GeoInfo
::
get_typed_group_attribute
(int group, const char *name, int type) const¶ Returns an
Attribute
, if one exists, with the specified name and type. This only looks in the specified group and returnsNULL
if it doesn’t find a matching attribute.
There are equivalent methods for getting an AttribContext
:
-
const AttribContext *
GeoInfo
::
get_attribcontext
(const char *name) const¶ Returns an
AttribContext
with the specified name and any type, using the search order above.
-
const AttribContext *
GeoInfo
::
get_typed_attribcontext
(const char *name, int type) const¶ Returns any
AttribContext
with the specified name and type, using the search order above. If there is an attribute with a matching name but a different type, this returnsNULL
.
-
const AttribContext *
GeoInfo
::
get_group_attribcontext
(int group, const char *name) const¶ Returns an
AttribContext
, if one exists, with the specified name and any type. This only looks in the specified group and returnsNULL
if it doesn’t find one.
-
const AttribContext *
GeoInfo
::
get_typed_group_attribcontext
(int group, const char *name, int type) const¶ Returns an
Attribute
, if one exists, with the specified name and type. This only looks in the specified group and returnsNULL
if it doesn’t find a matching attribute.
Adding Attributes¶
To add an attribute to an object, use:
-
const AttribContext *
GeoInfo
::
writable_attribcontext
(int obj, GroupType group, const char *name, AttribType type) const¶ Get or create an attribute on a particular object and return an
AttribContext
for it. TheAttribContext
has the group ID, attribute name, and an item type specified by thegroup
,name
, andtype
parameters respectively.
Deleting attributes¶
The GeoInfo
class provides this method:
-
void
GeoInfo
::
delete_group_attribute
(int group, const char *name, int type = INVALID_ATTRIB)¶
If you leave the type set to the default value, INVALID_ATTRIB
, it does not
take the attribute type into consideration when finding the attribute to
delete. Otherwise, it only deletes an attribute of that type.
Standard attributes¶
There are a number of predefined attributes that NUKE recognises:
Attribute Name |
Group |
Meaning |
---|---|---|
“uv” |
Group_Points Group_Vertices |
Texture coordinates, stored as a vector4 |
“N” |
Group_Points Group_Vertices Group_Primitives |
Point, vertex, and surface normals stored as a vector3 |
“Cf” |
Group_Points |
Surface colour |
“pw” |
Group_Points |
World-space point |
“vel” |
Group_Points |
Per-point velocity, used by the ScanlineRenderer for motion blur |