IDA3Statics Interface

The IDA3Statics interface is the COM interface that extends the IDAStatics and IDA2Statics interfaces. These methods, with an appended "Ex," specify arrays as a size and a fixed array, rather than as a VARIANT. Specifying arrays makes the methods easier to call in C++, but not using a VARIANT means you can't call them from script.

From the IDA3Statics interface you can access all the methods listed in the DAStatics class in the Scripting Reference and in the IDAStatics and IDA2Statics interfaces in the COM/C++ Reference.

This interface inherits from IDispatch. Like pure COM interfaces, such as IUnknown, IDispatch exposes objects, methods, and properties to applications. Unlike IUnknown, IDispatch members are identified with human-readable names, not as vtable indexes. IDispatch interfaces don't perform as well as pure COM interfaces.

IDA3Statics Methods

LinearGradientMulticolorEx Creates a DAImage object that is a linear fill of an array of colors at an array of positions. The positions define vertical bands from left to right.

RadialGradientMulticolorEx Creates a DAImage object with a radial fill created from an array of colors at an array of positions in concentric circles from the image's center.

SequenceArrayEx Creates a new behavior that, when started, will play multiple DABehavior objects in the order they appear in the array.

TriMeshEx Creates a set of triangle meshes that you can use to construct almost any geometry.

IDA3Statics::LinearGradientMulticolorEx

IDA3Statics Interface

Creates a DAImage object that is a linear fill of an array of colors at an array of positions. The positions define vertical bands from left to right. This function reads an array of colors and an array of positions. The positions determine the band for each corresponding color.

Note You can only use this function with Microsoft® DirectAnimation® versions later than 6.0, for example, version 6.00.06.xxx or later. Versions with this function are available in Microsoft Internet Explorer 5, Microsoft Windows® 98 Second Edition, and Windows 2000.

Syntax

HRESULT LinearGradientMulticolorEx(
    int nOffsets,
    IDANumber *offsets[],
    int nColors,
    IDAColor *colors[],
    IDAImage **result
);

Parameters

nOffsets
[in] Size of the offsets array.
offsets
[in, size_is(nOffsets)] Pointer to an array of DANumber objects or doubles representing the positions of the bands at which the different colors should be used for the gradient.

nColors
[in] Size of the colors array.
colors
[in, size_is(nColors)] Pointer to an array of DAColor objects representing the colors of bands at the different positions.

result
[out] Address of a pointer to a DAImage object with the linear gradient fill.

Return Value

Returns an HRESULT value that indicates the success of the method or the reason why it failed. This HRESULT depends on the implementation of the interface.

IDA3Statics::RadialGradientMulticolorEx

IDA3Statics Interface

Creates a DAImage object that is an image of infinite size with a radial fill created from an array of colors at an array of positions in concentric circles from the image's center. This method reads an array of colors and an array of positions. The positions determine the range along the radius for each corresponding color. The color of the largest radius fills the outer part of the image.

Note You can only use this function with DirectAnimation versions later than 6.0, for example, version 6.00.06.xxx or later. Versions with this function are available in Microsoft Internet Explorer 5, Windows 98 Second Edition, and Windows 2000.

Syntax

HRESULT RadialGradientMulticolorEx(
    int nOffsets,
    IDANumber *offsets[], 
    int nColors,
    IDAColor *colors[],
    IDAImage **result
);

Parameters

nOffsets
[in] Size of the offsets array.
offsets
[in, size_is(nOffsets)] Pointer to an array of DANumber objects or doubles representing positions along the image's radius at which the different colors should be used for the gradient.

nColors
[in] Size of the colors array.
colors
[in, size_is(nColors)] Pointer to an array of DAColor objects representing the colors at the different offsets along the image's radius.

result
[out] Address of a pointer to a DAImage object with the radial gradient fill.

Return Value

Returns an HRESULT value that indicates the success of the method or the reason why it failed. This HRESULT depends on the implementation of the interface.

IDA3Statics::SequenceArrayEx

IDA3Statics Interface

Creates a new behavior that, when started, will play multiple DABehavior objects in the order they appear in the array.

Syntax

HRESULT SequenceArrayEx(
    LONG sz,
    IDABehavior *bvrs,
    IDABehavior **ret
    );

Parameters

sz
[in] Size of the bvrs array.
bvrs
[size_is(sz), in] Pointer to an array of DABehavior objects that make up a sequence in the order in which they appear in the array.
ret
[out] Address of a pointer to the DABehavior object that contains the sequence of behaviors.

Return Value

Returns an HRESULT value that indicates the success of the method or the reason why it failed. This HRESULT depends on the implementation of the interface.

IDA3Statics::TriMeshEx

IDA3Statics Interface

Creates a set of triangle meshes that you can use to construct almost any geometry.

Syntax

HRESULT TriMeshEx(
    int nTriangles,
    int nPositions,
    float positions[],
    int nNormals,
    float normals[],
    int nSurfCoords,
    float surfCoords[],
    int nIndices,
    int indices[],
    IDAGeometry **result
);

Parameters

nTriangles
[in] Integer specifying the number of triangles in the mesh.
nPositions
[in] Size of the positions array.
positions
[in, size_is(nPositions)] Array that, for each triangle in the mesh, gives the 3-D locations of the three triangle vertices. The array of vertex positions cannot be empty (have no vertex positions). Positions can either be an array of DAPoint3 objects or a flat array (for example, V1x, V1y, V1z, V2x, V2y, V2z, V3x, V3y, V3z, ...) of floating-point triples. For the floating-point types, the number of values in the array must be a multiple of three.
nNormals
[in] Size of the normals array.
normals
[in, size_is(nNormals)] Array that, for each triangle vertex in the mesh, contains a vector that is perpendicular to the theoretical underlying surface of the vertex and points toward the outside of the surface. Normals can either be an array of DAVector3 objects or a flat array (for example, V1x, V1y, V1z, V2x, V2y, V2z, V3x, V3y, V3z, ...) of floating-point triples. For the floating-point types, the number of values in the array must be a multiple of three. This array must contain at least one normal. All normals are set to unit length on construction of the mesh, so you don't need to worry about the length of the normals, as long as they are nonzero.

nSurfCoords
[in] Size of the surfCoords array.
surfCoords
[in, size_is(nSurfCoords)] Array that, for each triangle vertex in the mesh, contains the 2-D location of the vertex on the surface of the underlying theoretical object. For example, on a sphere, the 2-D coordinates could correspond to latitude and longitude. Surface coordinates consist of an up value (u) that lies along the y-axis, and a direction value (v) along the z-axis. Surface coordinates can either be an array of DAPoint2 objects, or a flat array (for example, U1, V1, U2, V2, U3, V3, ...) of floating-point doubles. For the floating-point types, the number of values in the array must be a multiple of two. This array must contain at least one surface coordinate.

nIndices
[in] Size of the indices array.
indices
[in, size_is(nIndices)] Array that specifies the vertices of each triangle in the mesh. The first six values in indices specify step-stride information, and the rest of the values are indices that point to values in the positions, normals, and surfCoords arrays to describe each vertex in order, and construct triangles three vertices at a time. The first vertex is vertex 0. The indices are a flat array of integer triples. See Remarks for more information and examples. This array can be null, in which case the vertices are accessed sequentially from the other arrays.

result
[out] Address of a pointer to a DAGeometry object constructed from the specified triangle mesh.

Return Value

Returns an HRESULT value that indicates the success of the method or the reason why it failed. This HRESULT depends on the implementation of the interface.

Remarks

The front face of each triangle is defined by the counterclockwise orientation of the triangle vertices. As you look at the front of the triangle, the vertices should proceed counterclockwise around the boundary.
The simplest indices array is an empty array (null array or zero length). In this case, the vertices are accessed sequentially from the three vertex data arrays, with a triangle constructed three vertices at a time. The positions, normals, and surfCoords arrays must all have 3T elements, where T is the number of triangles. If you are using flat arrays, the positions and normals arrays must contain 3 × 3T floating-point numbers, while the surfCoords array must contain 2 × 3T floating-point numbers.
For example, the following is a triangle mesh with two triangles and an empty indices array.
nTriangles:   2
positions:    P0, P1, P2, P3, P4, P5      (values in the array are DAPoint3 objects)
normals:      N0, N1, N2, N3, N4, N5      (values in the array are DAVector3 objects)
surfCoords:   S0x,S0y, S1x,S1y, S2x,S2y,  (values in the array are floating-point numbers)
              S3x,S3y, S4x,S4y, S5x,S5y
Indices:      null
The resultant triangles from this mesh are:
Triangle 1:  {P0,N0,S0}, {P1,N1,S1}, {P2,N2,S2}
Triangle 2:  {P3,N3,S3}, {P4,N4,S4}, {P5,N5,S5}
An empty indices array is preferable when all of the vertex data are DirectAnimation elements (such as DAPoint3 or DAVector3) rather than floating-point numbers. This is because DirectAnimation elements are specified by reference, so you don't have overhead in specifying a vertex multiple times.
For example, a cube is constructed from 6 × 2 triangles, which means 36 vertex references in all. However, there are only eight unique vertices in a cube. With floating-point numbers, you have to respecify the full vertex data for each vertex (because floating-point numbers are specified by value), which means data duplication in the unindexed form.
For triangle meshes that are indexed, the indices array contains six integers specifying step-stride information, before the index data.
The step-stride information is contained in the first six integers, as follows:
            [0]  positions Step
            [1]  positions Stride
            [2]  normals Step
            [3]  normals Stride
            [4]  surfCoords Step
            [5]  surfCoords Stride
The step gives the offset to the first element in the indices array that contains the first index for the positions, normals, or surfCoords array, and the stride gives the incremental offset to the next element in the indices array that contains the index for the positions, normals, or surfCoords array.
For example, if indices[0] is 6, then the sixth element in the indices array, indices[6], is the first index for the positions array.
For example, consider a triangle mesh that defines a cube.
nTriangles: 12
positions[0]:  { 1,  1,  1}
positions[1]:  {-1,  1,  1}
positions[2]:  {-1,  1, -1}
positions[3]:  { 1,  1, -1}
positions[4]:  { 1, -1,  1}
positions[5]:  {-1, -1,  1}
positions[6]:  {-1, -1, -1}
positions[7]:  { 1, -1, -1}

normals[0]:    { 1,  0,  0}
normals[1]:    {-1,  0,  0}
normals[2]:    { 0,  1,  0}
normals[3]:    { 0, -1,  0}
normals[4]:    { 0,  0,  1}
normals[5]:    { 0,  0, -1}

surfCoords[0]: { 1, 0 }
surfCoords[1]: { 0, 1 }
surfCoords[2]: { 0, 0 }
surfCoords[3]: { 1, 1 }

indices[ 0, 1]:    6, 3      // positions step, stride
indices[ 2, 3]:    7, 3      // normals step, stride
indices[ 4, 5]:    8, 3      // surfCoords step, stride

// top face
indices[ 6, 7, 8]: 0, 2, 0   // triangle 1, vertex 1,
                             // index to values in positions/normals/surfCoords arrays
indices[ 9,10,11]: 2, 2, 1   // triangle 1, vertex 2,
                             // index in positions/normals/surfCoords arrays
indices[12,13,14]: 1, 2, 2   // triangle 1, vertex 3,
                             // index in positions/normals/surfCoords arrays

indices[15,16,17]: 0, 2, 0   // triangle 2, vertex 1,
                             // index in positions/normals/surfCoords arrays
indices[18,19,20]: 3, 2, 3   // triangle 2, vertex 2,
                             // index in positions/normals/surfCoords arrays
indices[21,22,23]: 2, 2, 1   // triangle 2, vertex 3,
                             // index in positions/normals/surfCoords arrays

// bottom face
indices[24,25,26]: 6, 3, 0   // triangle 3, vertex 1 
indices[27,28,29]: 4, 3, 1   // triangle 3, vertex 2
indices[30,31,32]: 5, 3, 2   // triangle 3, vertex 3

indices[24,25,26]: 6, 3, 0   // triangle 4, vertex 1 
indices[27,28,29]: 7, 3, 3   // triangle 4, vertex 2
indices[30,31,32]: 4, 3, 1   // triangle 4, vertex 3

// left face
indices[33,34,35]: 6, 1, 0   // triangle 5, vertex 1
indices[36,37,38]: 4, 1, 1   // triangle 5, vertex 2
indices[39,40,41]: 5, 1, 2   // triangle 5, vertex 3

indices[42,43,44]: 6, 1, 0   // triangle 6, vertex 1
indices[45,46,47]: 7, 1, 3   // triangle 5, vertex 2
indices[48,49,50]: 4, 1, 1   // triangle 5, vertex 3

// right face
...
// front face
...
// back face
...
In this case, the step-stride information is set for interleaved vertex data—vertex position, and then vertex normal, and then vertex surface coordinates—and none of the three vertex arrays share the same indices. However, step-stride pairs can be shared for vertex data, or set to repeat a value. Consider the triangle mesh for a flat panel to form a grid of four squares, two triangles per square:
 
nTriangles:  8

positions[0]:  {  0,  0,  0 }
positions[1]:  { .5,  0,  0 }
positions[2]:  {  1,  0,  0 }
positions[3]:  {  0, .5,  0 }
positions[4]:  { .5, .5,  0 }
positions[5]:  {  1, .5,  0 }
positions[6]:  {  0,  1,  0 }
positions[7]:  { .5,  1,  0 }
positions[8]:  {  1,  1,  0 }

normals[0]:    {  0,  0,  1 }     // one normal for entire mesh

surfCoords[0]: {  0,  0 }
surfCoords[1]: { .5,  0 }
surfCoords[2]: {  1,  0 }
surfCoords[3]: {  0, .5 }
surfCoords[4]: { .5, .5 }
surfCoords[5]: {  1, .5 }
surfCoords[6]: {  0,  1 }
surfCoords[7]: { .5,  1 }
surfCoords[8]: {  1,  1 }

indices[0,1]: 7,1     // positions step, stride
indices[1,2]: 6,0     // normals step, stride
indices[3,4]: 7,1     // surfCoords step, stride

indices[6]:   0       // normal index for all vertices

indices[ 7, 8, 9]:  0,1,3    // triangle 1
indices[10,11,12]:  3,1,4    // triangle 2
indices[13,14,15]:  3,4,6    // triangle 3
indices[16,17,18]:  6,4,7    // triangle 4
indices[19,20,21]:  1,2,4    // triangle 5
indices[22,23,24]:  4,2,5    // triangle 6
indices[25,26,27]:  4,5,7    // triangle 7
indices[28,29,30]:  7,5,8    // triangle 8
In this example, normals[0] is reused over and over for each vertex (stride 0), and both positions and surfCoords share the same index stream (step 7, stride 1). Without the step-stride model, the index array would require 3 properties per vertex times 3 vertices per triangle times 8 triangles, and would equal 72 entries rather than 31. For reasonable grids of this form (for example, 20 × 20), the cost of the step-stride model approaches one third that of the "list everything" model.
The other reason for the step-stride model is that for auto-generated surface coordinates and normals, the step-stride model eliminates indices altogether for some vertex properties, dramatically reducing the size and complexity of meshes.
Whether the mesh topology is described with an empty or nonempty indices array, the topology itself can't change. This means the indices array can't change. Topology is constant in a triangle mesh. If it weren't, the effort to determine how the triangle mesh changes with time would severely hamper performance. New topologies for a given mesh are best handled with a flexible enough initial topology (for example, if a seam is to open in a ball, the seam vertices should not be shared by both sides), or by accessing a new geometry. However, vertex positions, normals, and surface coordinates themselves can change, so that animate positions could be used to model a waving flag, for example.

Example

Note: You must have DirectAnimation version 6.00.06.xxx or later installed to display these samples.
The following examples show an octahedron created with an unindexed triangle mesh (no indices array) and an indexed triangle mesh (non-NULL indices array).
Unindexed Sample

Indexed Sample

LinearGradientMulticolorEx	Creates a DAImage object that is a linear fill of an array of colors at an array of positions. The positions define vertical bands from left to right.
RadialGradientMulticolorEx	Creates a DAImage object with a radial fill created from an array of colors at an array of positions in concentric circles from the image's center.
SequenceArrayEx	Creates a new behavior that, when started, will play multiple DABehavior objects in the order they appear in the array.
TriMeshEx	Creates a set of triangle meshes that you can use to construct almost any geometry.