AIMeshSuite Struct Reference
[API Suite List]

This suite and related suites provides functions for creating and managing mesh objects, which are art object of type kMeshArt. More...

#include <AIMesh.h>

List of all members.

Public Attributes
AIAPI AIErr(*	InitCartesian )(AIArtHandle mesh, ai::int32 i, ai::int32 j)
	Sets the dimensions of a mesh object.
AIAPI AIErr(*	InitPolar )(AIArtHandle mesh, ai::int32 i, ai::int32 j)
	Not implemented.
AIAPI AIErr(*	GetKind )(AIArtHandle mesh, ai::int32 *kind)
	Retrieves the type of the mesh.
AIAPI AIErr(*	GetSize )(AIArtHandle mesh, ai::int32 *i, ai::int32 *j)
	Retrieves the size of a mesh (number of patches).
AIAPI AIErr(*	NewSelection )(AIArtHandle mesh, AIBoolean all, AIMeshSelection *selection)
	Creates a new selection object for a mesh.
AIAPI AIErr(*	GetSelection )(AIArtHandle mesh, AIMeshSelection *selection)
	Retrieves the visible selection for a mesh; see AIMeshSelectionSuite.
AIAPI AIErr(*	GetPatch )(AIArtHandle mesh, ai::int32 i, ai::int32 j, AIMeshPatchIterator *patch)
	Creates a patch iterator a given patch in a mesh.
AIAPI AIErr(*	GetStartPatch )(AIArtHandle mesh, AIMeshPatchIterator *patch)
	Creates a patch iterator for which calling AIMeshPatchIteratorSuite::Next() repeatedly is guaranteed to visit all patches.
AIAPI AIErr(*	GetNode )(AIArtHandle mesh, ai::int32 i, ai::int32 j, AIMeshVertexIterator *vertex)
	Creates a vertex iterator for a given node in a mesh.
AIAPI AIErr(*	GetStartVertex )(AIArtHandle mesh, AIMeshVertexIterator *vertex)
	Creates a vertex iterator for which calling AIMeshVertexIteratorSuite::Next() repeatedly is guaranteed to visit all vertices.
AIAPI AIErr(*	GetStartSegment )(AIArtHandle mesh, AIMeshSegmentIterator *segment)
	Creates a segment iterator for which calling AIMeshSegmentIteratorSuite::Next() repeatedly is guaranteed to visit all segments.
AIAPI void(*	GetColorSpace )(AIArtHandle mesh, AIColorTag *kind, AICustomColorHandle *custom)
	Retrieves the color space used to render a mesh.
AIAPI AIBoolean(*	InvertPoint )(AIArtHandle mesh, AIRealPoint *point, AIReal *u, AIReal *v)
	Converts a point in artwork coordinates to the (u,v) coordinates of that point within a mesh.
AIAPI void(*	EvalPoint )(AIArtHandle mesh, AIReal u, AIReal v, AIRealPoint *point)
	Converts a point in the (u,v) coordinates of a mesh to artwork coordinates.
AIAPI void(*	EvalColor )(AIArtHandle mesh, AIReal u, AIReal v, AIColor *color)
	Retrieves the color of a mesh at a given point.
AIAPI void(*	EvalOpacity )(AIArtHandle mesh, AIReal u, AIReal v, AIReal *opacity)
	Retrieves the opacity of a mesh at a given point.
AIAPI AIErr(*	Transform )(AIArtHandle mesh, AIRealMatrix *matrix)
	Transforms the points of a mesh by a transformation matrix.
AIAPI AIErr(*	MapPoints )(AIArtHandle mesh, AIMeshPointMap f, void *userData)
	Transforms the points of a mesh according to a developer-defined mapping function.
AIAPI AIErr(*	MapColors )(AIArtHandle mesh, AIMeshColorMap f, void *userData)
	Transforms the colors of a gradient mesh according to a developer-defined mapping function.
AIAPI void(*	QueryColors )(AIArtHandle mesh, AIMeshColorQuery f, void *userData)
	Passes the colors of a gradient mesh to a developer-defined query function.
AIAPI AIErr(*	InsertU )(AIArtHandle mesh, AIReal u, ai::int32 *i)
	Splits a mesh at a point on the U axis and reports the index of the resulting grid line.
AIAPI AIErr(*	InsertV )(AIArtHandle mesh, AIReal v, ai::int32 *j)
	Splits a mesh at a point on the V axis and reports the index of the resulting grid line.
AIAPI AIErr(*	DeleteGridLines )(AIArtHandle mesh, AIReal u, AIReal v)
	Removes those lines of a mesh grid passing through a (U,V) point.
AIAPI void(*	TrackBegin )(AIArtHandle mesh)
	Starts tracking for mouse movement over a mesh.
AIAPI void(*	TrackEnd )(AIArtHandle mesh)
	Stops tracking for mouse movement over a mesh.
AIAPI AIErr(*	EndSelectionChanges )(void)
	Stops the recording of selection changes for a mesh in the Undo history.
AIAPI AIErr(*	DropColor )(AIHitRef hit, const AIColor *color)
	Drops a color onto an element of a mesh, as if a user dragged the color from, for example, the Swatch palette.
AIAPI AIErr(*	GetRelativeU )(AIArtHandle mesh, ai::int32 i, AIReal *u)
	Converts an I-axis integer coordinate in a mesh (in the range [0..numPatches]) to the corresponding U-axis coordinate, in the range [0..1].
AIAPI AIErr(*	GetRelativeV )(AIArtHandle mesh, ai::int32 j, AIReal *v)
	Converts a J-axis integer coordinate in a mesh (in the range [0..numPatches]) to the corresponding V-axis coordinate in the range [0..1].
AIAPI AIBoolean(*	GetOverprint )(AIArtHandle mesh)
	Retrieves the overprint fill attribute from a mesh object.
AIAPI AIErr(*	SetOverprint )(AIArtHandle mesh, AIBoolean overprint)
	Sets the overprint fill attribute for a mesh object.

---

Detailed Description

This suite and related suites provides functions for creating and managing mesh objects, which are art object of type kMeshArt.

A mesh object represents a grid that can be used to apply colors to art, or to deform art in an envelope; see the AIEnvelopeSuite.

This suite provides functions for manipulating a mesh as a whole.

• Additional suites allow you to traverse and manipulate the elements of a mesh (patches, vertices and segments). See Mesh Iterators.
• Different sets of elements in a mesh can be selected. The selection is represented by a mesh selection object. The AIMeshSelectionSuite allows you to manipulate selections for a mesh.
• The AIMeshHitSuite provides functions that operate on the results of hit testing for meshes (see AIHitTestSuite).

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIMeshSuite and kAIMeshVersion.

Mesh Terminology

A mesh can be considered an array of patches, where each patch has four sides which it shares with its neighbors. The corners of a patch are nodes to which color is applied. The colors of the corners then blend across the interior of the patch.

The patches are defined by cubic bezier curves, joined together to form the mesh. The point at which two or more beziers meet is called a knot. To reduce the visual complexity, only a subset of the knots are visible when a mesh is displayed. A visible knot is called a vertex. The sequence of beziers between two vertices is called a segment.

Just as for the beziers describing a path, a user can adjust the shape of the curve between two vertices. The points that manipulate the shape are called controls. Unlike a path, the curve might not be a single bezier, so the controls might not be coincident with the points of the bezier control polygon.

A coordinate system can be imposed on a mesh. For an M by N patch mesh, the coordinates range from [0..M] and [0..N]. Integer values of the coordinates refer to nodes. Non-integer values refer to points in the interior or on the sides of patches. When using strictly integer values, the axes are called the I and J axes. When using real values, they are called the U and V axes.

When traversing a mesh, a direction along the axes can be increasing or decreasing; this kind of direction is called the sense. A direction around a patch can be clockwise or counterclockwise. The term direction is reserved for this usage.

For example, for the node at (2,2):

• (3,1) is the next node increasing along the I axis.
• (2,1) is the next node decreasing along the J axis.
• (1,2) is the next node counterclockwise around patch (1,1).
• (2,1) is the next node clockwise around patch (1,1).

Mesh Iterators

Iterator objects allow you to traverse and manipulate the elements of a mesh. There are different iterators for each of the types of elements; patches, vertices and segments. There is a suite of functions for each type of iterator, the AIMeshPatchIteratorSuite, the AIMeshVertexIteratorSuite, and the AIMeshSegmentIteratorSuite.

Iterator objects are reference counted. The initial reference count is one, and you do not typically need to increment it. You must, however, use the appropriate Release() function to decrement the count when you no longer need the object. Failure to do so causes memory leaks.

Each type of iterator has an AtEnd method, which returns true when an iterator has walked off the mesh. After the end, the iterator cannot be reversed; that is you can no longer get the previous element.

An iterator has a set of Next and Prev methods for iteration.

• The simple Next and Prev methods are used with iterators obtained from a GetStart method. Repeated calls to Next guarantee that every element is visited once and only once. The order of traversal is undefined.
• The methods NextI, PrevI, NextJ, PrevJ are for traversing the elements along a given axis.
• A segment iterator has an axis and direction, determined by the start vertex and end vertex. The NextOnPatch and PrevOnPatch methods for segment iterators differ from NextOnAxis and PrevOnAxis only when they encounter a corner of a patch. In this case, they switch to a new axis by making a half turn either clockwise or counter clockwise.

---

Member Data Documentation

AIAPI AIErr(* AIMeshSuite::DeleteGridLines)(AIArtHandle mesh, AIReal u, AIReal v)

Removes those lines of a mesh grid passing through a (U,V) point.

Drawn grid lines pass through integer values. If both U and V are integers, removes both a horizontal and a vertical grid line. If only one is an integer, removes only one line.

Parameters:

	mesh	The mesh object.
	u	The U-axis coordinate.
	v	The V-axis coordinate.

AIAPI AIErr(* AIMeshSuite::DropColor)(AIHitRef hit, const AIColor *color)

Drops a color onto an element of a mesh, as if a user dragged the color from, for example, the Swatch palette.

Parameters:

	hit	A hit object that identifies the part of mesh. See AIHitTestSuite.
	color	The color.

AIAPI AIErr(* AIMeshSuite::EndSelectionChanges)(void)

Stops the recording of selection changes for a mesh in the Undo history.

Use after a change to selection, so that subsequent changes to other properties can be undone without undoing the selection.

Parameters:

mesh

The mesh object.

See also:

AIUndoSuite::UndoChanges()

AIAPI void(* AIMeshSuite::EvalColor)(AIArtHandle mesh, AIReal u, AIReal v, AIColor *color)

Retrieves the color of a mesh at a given point.

(Note that this function does not return an error code.)

Parameters:

	mesh	The mesh object.
	u	The U coordinate of the point.
	v	The V coordinate of the point.
	color	[out] A buffer in which to return the color.

AIAPI void(* AIMeshSuite::EvalOpacity)(AIArtHandle mesh, AIReal u, AIReal v, AIReal *opacity)

Retrieves the opacity of a mesh at a given point.

(Note that this function does not return an error code.)

Parameters:

	mesh	The mesh object.
	u	The U coordinate of the point.
	v	The V coordinate of the point.
	opacity	[out] A buffer in which to return the color.

AIAPI void(* AIMeshSuite::EvalPoint)(AIArtHandle mesh, AIReal u, AIReal v, AIRealPoint *point)

Converts a point in the (u,v) coordinates of a mesh to artwork coordinates.

(Note that this function does not return an error code.)

Parameters:

	mesh	The mesh object.
	u	The U coordinate of the point.
	v	The V coordinate of the point.
	point	[out] A buffer in which to return the converted point in artwork coordinates.

AIAPI void(* AIMeshSuite::GetColorSpace)(AIArtHandle mesh, AIColorTag *kind, AICustomColorHandle *custom)

Retrieves the color space used to render a mesh.

The colors of the nodes of the mesh can be drawn from different color spaces, which are converted to a single color space for rendering. (Note that this function does not return an error code.)

Parameters:

	mesh	The mesh object.
	kind	[out] A buffer in which to return the color type.
	custom	[out] A buffer in which to return the custom color, if kind is kCustomColor.

AIAPI AIErr(* AIMeshSuite::GetKind)(AIArtHandle mesh, ai::int32 *kind)

Retrieves the type of the mesh.

(Only cartesian meshes are implemented.)

Parameters:

	mesh	The mesh object.
	kind	[out] A buffer in which to return the type, a AIMeshKind value.

AIAPI AIErr(* AIMeshSuite::GetNode)(AIArtHandle mesh, ai::int32 i, ai::int32 j, AIMeshVertexIterator *vertex)

Creates a vertex iterator for a given node in a mesh.

Parameters:

	mesh	The mesh object.
	i	The 0-based I-axis index of the node.
	j	The 0-based J-axis index of the node.
	vertex	[out] A buffer in which to return the vertex iterator.

AIAPI AIBoolean(* AIMeshSuite::GetOverprint)(AIArtHandle mesh)

Retrieves the overprint fill attribute from a mesh object.

(Note that this function does not return an error code.)

Parameters:

mesh

The mesh object.

Returns:

True if overprint is on, false if it is off.

AIAPI AIErr(* AIMeshSuite::GetPatch)(AIArtHandle mesh, ai::int32 i, ai::int32 j, AIMeshPatchIterator *patch)

Creates a patch iterator a given patch in a mesh.

Parameters:

	mesh	The mesh object.
	i	The 0-based I-axis index of the patch.
	j	The 0-based J-axis index of the patch.
	patch	[out] A buffer in which to return the patch iterator.

AIAPI AIErr(* AIMeshSuite::GetRelativeU)(AIArtHandle mesh, ai::int32 i, AIReal *u)

Converts an I-axis integer coordinate in a mesh (in the range [0..numPatches]) to the corresponding U-axis coordinate, in the range [0..1].

See Mesh Terminology.

Parameters:

	mesh	The mesh object.
	i	The I-axis coordinate.
	u	[out] A buffer in which to return the U-axis coordinate.

AIAPI AIErr(* AIMeshSuite::GetRelativeV)(AIArtHandle mesh, ai::int32 j, AIReal *v)

Converts a J-axis integer coordinate in a mesh (in the range [0..numPatches]) to the corresponding V-axis coordinate in the range [0..1].

See Mesh Terminology.

Parameters:

	mesh	The mesh object.
	j	The J-axis coordinate.
	v	[out] A buffer in which to return the V-axis coordinate.

AIAPI AIErr(* AIMeshSuite::GetSelection)(AIArtHandle mesh, AIMeshSelection *selection)

Retrieves the visible selection for a mesh; see AIMeshSelectionSuite.

Changing the returned selection changes what the user sees.

Parameters:

	mesh	The mesh object.
	selection	[out] A buffer in which to return the selection.

AIAPI AIErr(* AIMeshSuite::GetSize)(AIArtHandle mesh, ai::int32 *i, ai::int32 *j)

Retrieves the size of a mesh (number of patches).

Parameters:

	mesh	The mesh object.
	i	[out] A buffer in which to return the number of patches along the I axis.
	j	[out] A buffer in which to return the number of patches along the J axis.

AIAPI AIErr(* AIMeshSuite::GetStartPatch)(AIArtHandle mesh, AIMeshPatchIterator *patch)

Creates a patch iterator for which calling AIMeshPatchIteratorSuite::Next() repeatedly is guaranteed to visit all patches.

Parameters:

	mesh	The mesh object.
	patch	[out] A buffer in which to return the patch iterator.

AIAPI AIErr(* AIMeshSuite::GetStartSegment)(AIArtHandle mesh, AIMeshSegmentIterator *segment)

Creates a segment iterator for which calling AIMeshSegmentIteratorSuite::Next() repeatedly is guaranteed to visit all segments.

Parameters:

	mesh	The mesh object.
	segment	[out] A buffer in which to return the segment iterator.

AIAPI AIErr(* AIMeshSuite::GetStartVertex)(AIArtHandle mesh, AIMeshVertexIterator *vertex)

Creates a vertex iterator for which calling AIMeshVertexIteratorSuite::Next() repeatedly is guaranteed to visit all vertices.

Parameters:

	mesh	The mesh object.
	vertex	[out] A buffer in which to return the vertex iterator.

AIAPI AIErr(* AIMeshSuite::InitCartesian)(AIArtHandle mesh, ai::int32 i, ai::int32 j)

Sets the dimensions of a mesh object.

The geometric and color data is set to default values.

Parameters:

	mesh	The mesh object.
	i	The number of patches along the I axis.
	j	The number of patches along the J axis.

AIAPI AIErr(* AIMeshSuite::InitPolar)(AIArtHandle mesh, ai::int32 i, ai::int32 j)

Not implemented.

AIAPI AIErr(* AIMeshSuite::InsertU)(AIArtHandle mesh, AIReal u, ai::int32 *i)

Splits a mesh at a point on the U axis and reports the index of the resulting grid line.

Parameters:

	mesh	The mesh object.
	u	The insertion point on the U axis.
	i	[out] A buffer in which to return the 0-based index of the new grid line.

AIAPI AIErr(* AIMeshSuite::InsertV)(AIArtHandle mesh, AIReal v, ai::int32 *j)

Splits a mesh at a point on the V axis and reports the index of the resulting grid line.

Parameters:

	mesh	The mesh object.
	v	The insertion point on the V axis.
	i	[out] A buffer in which to return the 0-based index of the new grid line.

AIAPI AIBoolean(* AIMeshSuite::InvertPoint)(AIArtHandle mesh, AIRealPoint *point, AIReal *u, AIReal *v)

Converts a point in artwork coordinates to the (u,v) coordinates of that point within a mesh.

(Note that this function returns a boolean value, not an error code.)

Parameters:

	mesh	The mesh object.
	point	The pointer to the point in artwork coordinates.
	u	[out] A buffer in which to return the U coordinate of the converted point.
	v	[out] A buffer in which to return the V coordinate of the converted point.

Returns:

True if the point lies inside the mesh (the u and v values are defined), false if it lies outside the mesh (the u and v values are not defined).

AIAPI AIErr(* AIMeshSuite::MapColors)(AIArtHandle mesh, AIMeshColorMap f, void *userData)

Transforms the colors of a gradient mesh according to a developer-defined mapping function.

Parameters:

	mesh	The mesh object.
	f	The color-mapping function.
	userData	Developer-defined data to pass through to the function.

AIAPI AIErr(* AIMeshSuite::MapPoints)(AIArtHandle mesh, AIMeshPointMap f, void *userData)

Transforms the points of a mesh according to a developer-defined mapping function.

Parameters:

	mesh	The mesh object.
	f	The point-mapping function.
	userData	Developer-defined data to pass through to the function.

AIAPI AIErr(* AIMeshSuite::NewSelection)(AIArtHandle mesh, AIBoolean all, AIMeshSelection *selection)

Creates a new selection object for a mesh.

Use the AIMeshSelectionSuite to query and manipulate the selection.

Parameters:

	mesh	The mesh object.
	all	When true, include all vertices and segments of the mesh in the selection. When false, create an empty selection.
	selection	[out] A buffer in which to return the selection.

See also:

GetSelection()

AIAPI void(* AIMeshSuite::QueryColors)(AIArtHandle mesh, AIMeshColorQuery f, void *userData)

Passes the colors of a gradient mesh to a developer-defined query function.

Does not modify the mesh colors. (Note that this function does not return an error code.)

Parameters:

	mesh	The mesh object.
	f	The color-querying function.
	userData	Developer-defined data to pass through to the function.

AIAPI AIErr(* AIMeshSuite::SetOverprint)(AIArtHandle mesh, AIBoolean overprint)

Sets the overprint fill attribute for a mesh object.

Parameters:

	mesh	The mesh object.
	overprint	True to turn overprint on, false to turn it off.

AIAPI void(* AIMeshSuite::TrackBegin)(AIArtHandle mesh)

Starts tracking for mouse movement over a mesh.

(Note that this function does not return an error code.)

Note:

For a tool that manipulates the control points of a mesh, call TrackBegin() before moving the control points (in response to mouse-down, for example) and TrackEnd() when done (in response to mouse-up). This ensures that selection handles are redrawn during the operation--otherwise the control points are not visible as they are modified.

Parameters:

mesh

The mesh object.

AIAPI void(* AIMeshSuite::TrackEnd)(AIArtHandle mesh)

Stops tracking for mouse movement over a mesh.

(Note that this function does not return an error code.)

Parameters:

mesh

The mesh object.

See also:

TrackBegin()

AIAPI AIErr(* AIMeshSuite::Transform)(AIArtHandle mesh, AIRealMatrix *matrix)

Transforms the points of a mesh by a transformation matrix.

Parameters:

	mesh	The mesh object.
	matrix	A pointer to the transformation matrix.

---

The documentation for this struct was generated from the following file:

• AIMesh.h