AIPathInterpolateSuite Struct Reference
[API Suite List]

This suite provides functions that allow you to interpolate paths and styles, creating a smooth blend between two existing art objects. More...

#include <AIPathInterpolate.h>

List of all members.

Public Attributes
AIAPI AIErr(*	SmoothColorBlendSteps )(AIArtHandle startPath, AIArtHandle endPath, AIReal densityLimit, ai::int16 *steps)
	Calculates the default number of steps for a smooth blend between two paths or compound paths, based primarily on the maximum distance in any color channel between the two paint styles, and assuming that the interpolated step objects will be placed with their centers on a straight line between the centers of the two blended objects.
AIAPI AIErr(*	GetPathSelectedSegmentCount )(AIArtHandle path, ai::int16 *count)
	Counts the number of segments of a path that are in `kSegmentPointSelected` state.
AIAPI AIErr(*	PathSelectionToAnchorIDs )(AIArtHandle path, ai::int16 count, AIAnchorIdentifier *anchorIDs)
	Translates from a partially selected path to arrays recording which points are selected, in the form of offsets.
AIAPI AIErr(*	PathSelectionToSegNumbers )(AIArtHandle path, ai::int16 count, ai::int16 *selectedPoints)
	Translates from a partially selected path to an array of selected points.
AIAPI AIErr(*	SelectAnchorPoints )(AIArtHandle path, ai::int16 count, ai::int16 *selectPoints)
	Selects a set of anchor points in a path.
AIAPI AIErr(*	InsertInterpolants )(AIArtHandle startPath, AIArtHandle endPath, AIRealPoint substituteCenter, AIArtHandle useStyleFromPath, ai::int16 steps, ai::int16 numMatchPairs, ai::int16 matches1, ai::int16 matches2, AIPathInstallData installData, PostInstallCB clientCallback)
	Creates and installs the paths that represent an interpolation between two existing paths.
AIAPI AIErr(*	MeasurePathSegments )(AIArtHandle path, ai::int16 ixStart, ai::int16 count, AIReal *segLengths, AIReal flatness)
	Calculates the length of a set of path segments.
AIAPI AIErr(*	NewStyleInterpolator )(AIStyleInterpolator *interpolator, AIArtHandle styleSource0, AIArtHandle styleSource1)
	Allocates and initializes a style interpolation object for use with `ApplyInterpolatedStyle()`.
AIAPI AIErr(*	DisposeStyleInterpolator )(AIStyleInterpolator interpolator)
	Frees memory for a style interpolator that is no longer needed.
AIAPI AIErr(*	ApplyInterpolatedStyle )(AIStyleInterpolator interpolator, AIArtHandle targetArt, AIReal fraction)
	Uses a style interpolator to create and apply an interpolated style to an interpolated art object.
AIAPI AIErr(*	NewArtStyleInterpolator )(AIStyleInterpolator *interpolator, AIArtStyleHandle style0, AIArtStyleHandle style1)
	Allocates and initializes a style interpolation object for use with `ApplyInterpolatedStyle()`.
AIAPI AIErr(*	GetInterpolatedArtStyle )(AIStyleInterpolator interpolator, AIReal fraction, AIArtStyleHandle *result)
	Retrieves an intermediate art style created by a style interpolation object that would be applied for a specific call to `ApplyInterpolatedStyle()`.
AIAPI AIBoolean(*	AppropriateForSmoothColor )(AIArtHandle art1, AIArtHandle art2)
	Reports whether two art objects are suitable for smooth color blending.
AIAPI AIErr(*	SmoothColorBlendStepsAlongPath )(AIArtHandle startPath, AIArtHandle endPath, AIReal densityLimit, ai::int16 *steps, AIReal pathDistance)
	Calculates the default number of steps for a smooth blend between two paths or compound paths, based primarily on the maximum distance in any color channel between the two paint styles, and assuming that the interpolated step objects will be placed with their centers on an arbitrary path of length `pathDistance`.

Detailed Description

This suite provides functions that allow you to interpolate paths and styles, creating a smooth blend between two existing art objects.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIPathInterpolateSuite and kAIPathInterpolateVersion.

Member Data Documentation

AIAPI AIErr(* AIPathInterpolateSuite::ApplyInterpolatedStyle)(AIStyleInterpolator interpolator, AIArtHandle targetArt, AIReal fraction)

Uses a style interpolator to create and apply an interpolated style to an interpolated art object.

Parameters:

	interpolator	The interpolation object, as returned by `NewStyleInterpolator` or `NewArtStyleInterpolator`.
	targetArt	The intermediate object to which to apply the style.
	fraction	The distance from the source objects. 0 to apply the style from the first source object, 1 to apply the style from the second source object, or an interpolation point between the two.

Note:: If the art styles are not comparable, the function ignores the fraction value and applies the style of the first source object.

AIAPI AIBoolean(* AIPathInterpolateSuite::AppropriateForSmoothColor)(AIArtHandle art1, AIArtHandle art2)

Reports whether two art objects are suitable for smooth color blending.

To be suitable, both must be either paths or compound paths, and be painted with different, simple solid colors (not gradients, patterns, or active styles). One or both objects can have transparency. (Note that this function returns a boolean value, not an error code.)

Parameters:

	art1	The first art object.
	art2	The second art object.

Returns:: True if the two objects are suitable for smooth color blending.

AIAPI AIErr(* AIPathInterpolateSuite::DisposeStyleInterpolator)(AIStyleInterpolator interpolator)

Frees memory for a style interpolator that is no longer needed.

Parameters:

interpolator

The style interpolation object. Upon return, this reference is invalid.

AIAPI AIErr(* AIPathInterpolateSuite::GetInterpolatedArtStyle)(AIStyleInterpolator interpolator, AIReal fraction, AIArtStyleHandle *result)

Retrieves an intermediate art style created by a style interpolation object that would be applied for a specific call to ApplyInterpolatedStyle().

Parameters:

	interpolator	The interpolation object, as returned by `NewStyleInterpolator` or `NewArtStyleInterpolator`.
	fraction	The distance from the source objects. 0 for the style from the first source object, 1 for the style from the second source object, or an interpolation point between the two.
	result	[out] A buffer in which to return the new art style.

AIAPI AIErr(* AIPathInterpolateSuite::GetPathSelectedSegmentCount)(AIArtHandle path, ai::int16 *count)

Counts the number of segments of a path that are in kSegmentPointSelected state.

Parameters:

	path	The path object.
	count	[out] A buffer in which to return the number of selected segments.

AIAPI AIErr(* AIPathInterpolateSuite::InsertInterpolants)(AIArtHandle startPath, AIArtHandle endPath, AIRealPoint *substituteCenter, AIArtHandle useStyleFromPath, ai::int16 steps, ai::int16 numMatchPairs, ai::int16 *matches1, ai::int16 *matches2, AIPathInstallData *installData, PostInstallCB clientCallback)

Creates and installs the paths that represent an interpolation between two existing paths.

/li If both paths are fully selected, or if either path is not selected at all, then the selection state of the anchor points is ignored, and both paths are entirely flattened to get the point correspondences for interpolation.

/li If one path is partially selected, and the other is fully or partially selected, the function builds anchor-point arrays corresponding to the partial selections and specified matches.

Parameters:

	startPath	The starting path. Can be `NULL` if end path is given.
	endPath	The ending path. Can be `NULL` if start path is given.
	substituteCenter	A point where all points gather at one end, if the path for that end is `NULL`. Ignored if both paths are specified.
	useStyleFromPath	If one of the two paths is `NULL` and the other is part of a compound path (an "extra hole"), this is the backmost object in the compound path for the other end.
	steps	The number of steps between the two paths.
	numMatchPairs	The number of values in the matches arrays. When positive, the corresponding values in the two match arrays specify pairs. When 0 or negative, the matches arrays are ignored, and matching starts at the top left corner of both paths for a closed path, or the leftmost endpoint for an open path, and proceeds clockwise.
	matches1	An array of match values of size `numMatchPairs`.
	matches2	An array of match values of size `numMatchPairs`.
	clientCallback	A developer-defined callback to call after each new path is installed. Can determine how the next path is installed, provide information for the insertion operation, or perform other post-processing on the new paths.

If NULL, the default behavior is to link each path to the previously created one. See AIPathInstallData.

AIAPI AIErr(* AIPathInterpolateSuite::MeasurePathSegments)(AIArtHandle path, ai::int16 ixStart, ai::int16 count, AIReal *segLengths, AIReal flatness)

Calculates the length of a set of path segments.

Parameters:

	path	The path object.
	ixStart	The starting point.
	count	[in, out] The number of members allocated for the segment-length array. Returns the number of segment lengths calculated.
	segLengths	[out] A buffer in which to return an array of segment length values. You must allocate memory for this array, and free it when no longer needed.
	flatness	An upper bound on the error between the line segments and the true curve.

AIAPI AIErr(* AIPathInterpolateSuite::NewArtStyleInterpolator)(AIStyleInterpolator *interpolator, AIArtStyleHandle style0, AIArtStyleHandle style1)

Allocates and initializes a style interpolation object for use with ApplyInterpolatedStyle().

This version uses the style objects directly, and does not include object-specific data about how the style is applied to a particular object (random seeds, scale factors, gradient matrices, and so on) that is not encapsulated in the AIArtStyleHandle.

One, but not both of the source objects can be NULL. In this case, the interpolator applies a copy of the other art style. This avoids the need to interpolate down to nothing.

Parameters:

	interpolator	[out] A buffer in which to return the new interpolation object.
	style0	The first art style object.
	style1	The second art style object.

See also:: NewStyleInterpolator()

AIAPI AIErr(* AIPathInterpolateSuite::NewStyleInterpolator)(AIStyleInterpolator *interpolator, AIArtHandle styleSource0, AIArtHandle styleSource1)

Allocates and initializes a style interpolation object for use with ApplyInterpolatedStyle().

Not needed with InsertInterpolants(), which automatically applies interpolated styles to the paths it creates. Use when you create the intermediate objects yourself--for example, to apply interpolated styles to group objects or text objects, or to interpolate path outlines using a different technique.

This version includes object-specific data about how the style is applied to a particular object (random seeds, scale factors, gradient matrices, and so on) that is not encapsulated in the AIArtStyleHandle. For a version that creates an interpolation object from the styles themselves, see NewArtStyleInterpolator().

One, but not both of the source objects can be NULL. In this case, the interpolator applies a copy of the other art style. This avoids the need to interpolate down to nothing.

Parameters:

	styleSource0	The source art object for the first style.
	styleSource1	The source art object for the second style.

AIAPI AIErr(* AIPathInterpolateSuite::PathSelectionToAnchorIDs)(AIArtHandle path, ai::int16 count, AIAnchorIdentifier *anchorIDs)

Translates from a partially selected path to arrays recording which points are selected, in the form of offsets.

Ignores non-p0 selections. Use to store points across events that may insert or delete anchor points.

Parameters:

	path	The path object.
	count	The number of members allocated for the anchor-ID array. If less than the number of selected points, only this number are translated. If both paths are partially selected and the number of points differs, uses the lowest point count.
	anchorIDs	[out] A buffer in which to return an array of anchor ID values. All fractional parts of the `segmentOffset` values are zero. If fewer than `count` points are selected, the remaining members are filled with anchor IDs whose values are all 0. You must allocate memory for this array, and free it when no longer needed.

See also:: PathSelectionSegNumbers() (use to communicate with InsertInterpolants() when the number of segments is known.)

AIAPI AIErr(* AIPathInterpolateSuite::PathSelectionToSegNumbers)(AIArtHandle path, ai::int16 count, ai::int16 *selectedPoints)

Translates from a partially selected path to an array of selected points.

Ignores non-p0 selections. Use to communicate with InsertInterpolants() when the number of segments is known.

Parameters:

	path	The path object.
	count	The number of members allocated for the point array. If less than the number of selected points, only this number are translated. If both paths are partially selected and the number of points differs, uses the lowest point count.
	selectedPoints	[out] A buffer in which to return an array of point values. If fewer than `count` points are selected, the remaining members are filled with points whose values are all 0. You must allocate memory for this array, and free it when no longer needed.

See also:: PathSelectionToAnchorIDs() (use to store points across events that may insert or delete anchor points.)

AIAPI AIErr(* AIPathInterpolateSuite::SelectAnchorPoints)(AIArtHandle path, ai::int16 count, ai::int16 *selectPoints)

Selects a set of anchor points in a path.

Parameters:

	path	The path object.
	count	The number of members allocated for the point array.
	selectPoints	A set of point values, an array of size `count`. You must allocate memory for this array, and free it when no longer needed.

AIAPI AIErr(* AIPathInterpolateSuite::SmoothColorBlendSteps)(AIArtHandle startPath, AIArtHandle endPath, AIReal densityLimit, ai::int16 *steps)

Calculates the default number of steps for a smooth blend between two paths or compound paths, based primarily on the maximum distance in any color channel between the two paint styles, and assuming that the interpolated step objects will be placed with their centers on a straight line between the centers of the two blended objects.

Note:: If the objects are not appropriate for shading, either because there is no color channel difference (the objects are painted with the same color), or because they are painted with multiple colors (such as gradients and patterns), or because they have effects or their outline is too complex for shading (such as type objects, groups and symbols), the calculation is based on the separation between objects instead, so that the space between them is filled with objects that almost overlap or barely overlap. See AppropriateForSmoothColor() to determine whether this function will base the step calculation on a color difference or the spacial separation.

Parameters:

	startPath	The starting art object. Usually a path or compound path.
	endPath	The ending art object. Usually a path or compound path.
	densityLimit	When positive, calculates the maximum distance from a bounding box edge of one path to the corresponding bounding box edge of the other path, and takes the `densityLimit` value as the minimum separation (in document points) between consecutive interpolated edges within that span. Another way to think of this is that 1/densityLimit is the maximum number of interpolated path edges to place in a point of separation between bounding box edges.

For example, if the maximum bounding box edge distance between the two blended paths is 4 points, and the density limit is 0.125 (1/8), then steps are at most 32 no matter how different the colors are.

Use to avoid many paths crowded into a tiny distance, when the blend would look the same with a much smaller number of paths.

If the blend is intended for print, a value of about 1/4 to 1/8 point will give smooth color. If it is intended for screen only, a value of 1 pt may be sufficient.

Ignored if zero, negative, or greater than 4.0.

Parameters:

steps

[out] A buffer in which to return the number of steps.

See also:: SmoothColorBlendStepsAlongPath() for calculating an appropriate number of steps when the interpolated objects will not be placed along a straight line between the centers of the startPath and the endPath.

AIAPI AIErr(* AIPathInterpolateSuite::SmoothColorBlendStepsAlongPath)(AIArtHandle startPath, AIArtHandle endPath, AIReal densityLimit, ai::int16 *steps, AIReal pathDistance)

Calculates the default number of steps for a smooth blend between two paths or compound paths, based primarily on the maximum distance in any color channel between the two paint styles, and assuming that the interpolated step objects will be placed with their centers on an arbitrary path of length pathDistance.

Specifically intended for blends along non-default spine paths.

Note:: If the objects are not appropriate for shading, either because there is no color channel difference (the objects are painted with the same color), or because they are painted with multiple colors (such as gradients and patterns), or because they have effects or their outline is too complex for shading (such as type objects, groups and symbols), the calculation is based on the spacial separation between objects instead, so that the space between objects placed along a path of length pathDistance will be filled with objects that almost overlap or barely overlap. See AppropriateForSmoothColor() to determine whether this function will base the step calculation on the color difference or the separation along the spine path.

Parameters:

	startPath	The starting art object, usually a path or compound path.
	endPath	The ending art object, usually a path or compound path.
	densityLimit	When positive (and less than or equal to 4.0), calculates the maximum of `pathDistance` and of the maximum distance between corresponding bounding box edges of the two input objects, and takes the `densityLimit` value as the minimum distance between consecutive interpolated step centers placed along that distance. Another way to think of this is that 1/densityLimit is the maximum number of interpolated step centers to place within each point of the `pathDistance`.

For example, if the pathDistance is 10 pts, and the maximum bounding box edge separation is less than 10 pts, and the density limit is 0.125 (1/8), then the calculated steps will be at most 80 no matter how different the colors are.

Use to avoid many blend steps crowded into a short distance, when the blend would look as smooth with a much smaller number of steps.

Ignored if zero, negative, or greater than 4.0.

Parameters:

	steps	[out] A buffer in which to return the number of steps.
	pathDistance	Used to calculate the separation between the start and end objects, instead of the object bounds, when the distance is needed either for objects that are not appropriate for smooth color or to perform the density limit calculations. If the maximum bounding box edge separation is greater than this value, the bounding box edge separation is used instead.

If the objects are appropriate for smooth color, and the density limit is zero, this parameter is ignored, and the function returns the same number of steps as SmoothColorBlendSteps().

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

AIPathInterpolate.h

AIPathInterpolateSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIPathInterpolateSuite Struct Reference
[API Suite List]