AIEnvelopeSuite Struct Reference
[API Suite List]

This suite provides functions to create and manage envelopes, which allow you to apply a set of deformations to a set of source art objects. More...

#include <AIEnvelope.h>

List of all members.

Public Attributes
AIAPI AIErr(*	MakeEnvelope )(AIArtHandle art, ai::int32 numArt, AIArtHandle envelopeObject, AIEnvelopeOptions options, AIArtHandle *envelope)
	Creates an envelope for a given set of source art objects, or for the currently selected art if `art` is `nullptr` or `numArt` is 0.
AIAPI AIErr(*	WarpEnvelope )(AIArtHandle envelope, AIWarpStyle warpStyle, AIReal bend, AIReal horizDistort, AIReal vertDistort, AIBoolean rotate90)
	Redefines an envelope to use a predefined warp style.
AIAPI AIErr(*	ReleaseEnvelope )(AIArtHandle envelope)
	Replaces an envelope in the document with its source contents (in the original, undistorted state) and a mesh object.
AIAPI void(*	GetEnvelopeOptions )(AIArtHandle envelope, AIEnvelopeOptions *options)
	Retrieves the distortion options for an envelope.
AIAPI void(*	SetEnvelopeOptions )(AIArtHandle envelope, AIEnvelopeOptions *options)
	Sets the distortion options for an envelope.
AIAPI void(*	GetCurrentEnvelopeOptions )(AIEnvelopeOptions *options)
	Retrieves the default distortion options stored in application preferences.
AIAPI AIBoolean(*	IsEnvelope )(AIArtHandle envelope)
	Reports whether an art object is an envelope.
AIAPI AIBoolean(*	EditingMesh )(AIArtHandle envelope)
	Reports whether the mesh defining the distortion of an envelope is being edited.
AIAPI AIBoolean(*	EditingContents )(AIArtHandle envelope)
	Reports whether the contents of an envelope are being edited.
AIAPI AIErr(*	ToggleEditability )(AIArtHandle envelope)
	Switches between editing the mesh and the contents of an envelope.
AIAPI AIErr(*	GetEnvelopeObject )(AIArtHandle envelope, AIArtHandle *envelopeObject)
	Retrieves the envelope object for an art group.
AIAPI AIErr(*	SetEnvelopeObject )(AIArtHandle envelope, AIArtHandle envelopeObject)
	Sets the envelope object for an art group.
AIAPI AIErr(*	GetObjectsInEnvelope )(AIArtHandle envelope, AIArtHandle *objects)
	Retrieves the art objects being deformed by an envelope.
AIAPI AIErr(*	DeformArt )(AIArtHandle artToDeform, AIDictionaryRef deformParams, AIRealRect srcRect, AIArtHandle deformedArt, AIDeformProgressProc progressProc)
	Deforms an art object or group using the parameters in a dictionary.
AIAPI AIErr(*	GenerateDeformMeshFromPath )(AIArtHandle pathArt, AIArtHandle *meshArt)
	not implemented
AIAPI AIErr(*	GetEnvelopeType )(AIArtHandle envelope, AIEnvelopeType *type)
	Retrieves the type of an envelope (warp, mesh, or object).
AIAPI AIErr(*	UnconstrainedReshapePath )(const AIArtHandle inPath, const AIReal &param, const AIRealPoint &delta, bool shiftPressed)
	Reshapes a path object.
AIAPI AIErr(*	GetParamFromPathHitPoint )(const AIArtHandle pathHandle, AIRealPoint pointOnCurve, int segmentIndex, AIReal &param)
	Retrieves the t value for a point on a bezier curve.

Detailed Description

This suite provides functions to create and manage envelopes, which allow you to apply a set of deformations to a set of source art objects.

The name derives from the idea of putting paper artworks into an envelope, then bending or distorting the envelope.

The source art can be warped or deformed in various ways, as defined by an AIWarpStyle, with respect to a mesh, or grid. The envelope actions are available in the UI through the Object > Envelope Distort menu.

Deformations can only be applied directly to paths, compound paths, meshes, and images. To apply a distortion to other types of art objects in the source art, those objects must first be expanded; that is, converted to paths. Deformation options allow you to specify which types of art to expand and deform along with the paths and images.

The envelope for an art group, which encapsulates the deformation options, is represented as an art object of type kMeshArt. See also the AIMeshSuite.

The function DeformArt() allows you to apply the same kinds of deformations directly to a source art group, without creating an envelope object.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIEnvelopeSuite and kAIEnvelopeVersion.

Member Data Documentation

AIAPI AIErr(* AIEnvelopeSuite::DeformArt)(AIArtHandle artToDeform, AIDictionaryRef deformParams, AIRealRect *srcRect, AIArtHandle *deformedArt, AIDeformProgressProc progressProc)

Deforms an art object or group using the parameters in a dictionary.

Does not make an envelope object, but deforms the art in the same way an envelope would. The resulting art object is inserted in the art tree above the original art object in the paint order.

Parameters:

	artToDeform	The source art object or group, which must have a parent. The function does not modify this object in any way.
	deformParams	A dictionary containing the deformation parameters. Contains entries for these keys: `kAIDeformMeshKey`, `kAIDeformFidelityKey`, `kAIDeformOptionsKey`.
	srcRect	The bounding box of the source space (that is, the size the envelope would be), or `nullptr` to use the bounds of the source art.
	deformedArt	[out] A buffer in which to return the resulting art object.
	progressProc	A callback procedure for displaying a progress bar during computation (from which the user can cancel the operation) or `nullptr` to show no progress bar.

Returns:: The error kCanceledErr if user cancels the operation from the progress bar.

AIAPI AIBoolean(* AIEnvelopeSuite::EditingContents)(AIArtHandle envelope)

Reports whether the contents of an envelope are being edited.

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

Parameters:

envelope

The envelope object.

Returns:: True if the contents of the envelope are being edited.

See also:: ToggleEditability(), EditingMesh()

AIAPI AIBoolean(* AIEnvelopeSuite::EditingMesh)(AIArtHandle envelope)

Reports whether the mesh defining the distortion of an envelope is being edited.

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

Parameters:

envelope

The envelope object.

Returns:: True if the mesh is being edited.

See also:: ToggleEditability(), EditingContents()

AIAPI AIErr(* AIEnvelopeSuite::GenerateDeformMeshFromPath)(AIArtHandle pathArt, AIArtHandle *meshArt)

not implemented

AIAPI void(* AIEnvelopeSuite::GetCurrentEnvelopeOptions)(AIEnvelopeOptions *options)

Retrieves the default distortion options stored in application preferences.

Parameters:

options

[out] A buffer in which to return the default options structure,

AIAPI AIErr(* AIEnvelopeSuite::GetEnvelopeObject)(AIArtHandle envelope, AIArtHandle *envelopeObject)

Retrieves the envelope object for an art group.

Parameters:

	envelope	The art group.
	envelopeObject	[out] A buffer in which to return the envelope object.

AIAPI void(* AIEnvelopeSuite::GetEnvelopeOptions)(AIArtHandle envelope, AIEnvelopeOptions *options)

Retrieves the distortion options for an envelope.

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

Parameters:

	envelope	The envelope object.
	options	[out] A buffer in which to return the options structure,

AIAPI AIErr(* AIEnvelopeSuite::GetEnvelopeType)(AIArtHandle envelope, AIEnvelopeType *type)

Retrieves the type of an envelope (warp, mesh, or object).

Parameters:

	envelope	The envelope object.
	type	[out] A buffer in which to return the envelope type constant.

Note:: Added in AI13. Previously, the type was not stored with the object. For envelope objects created in earlier versions, returns kEnvelopeWarp for Envelope Warp and kEnvelopeMesh for all other types.

AIAPI AIErr(* AIEnvelopeSuite::GetObjectsInEnvelope)(AIArtHandle envelope, AIArtHandle *objects)

Retrieves the art objects being deformed by an envelope.

Parameters:

	envelope	The envelope object.
	objects	[out] A buffer in which to return the art group. This can be the edit group of envelope's source art group if the contents are being edited (that is, if `EditingContents()` would return true for `envelope`).

AIAPI AIErr(* AIEnvelopeSuite::GetParamFromPathHitPoint)(const AIArtHandle pathHandle, AIRealPoint pointOnCurve, int segmentIndex, AIReal &param)

Retrieves the t value for a point on a bezier curve.

Parameters:

	pathHandle	The path object.
	pointOnCurve	The point for which the t value has to be found.
	segmentIndex	The index of the path segment on which this point lies.
	param	[out] The calculated t value for the point.

AIAPI AIBoolean(* AIEnvelopeSuite::IsEnvelope)(AIArtHandle envelope)

Reports whether an art object is an envelope.

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

Parameters:

envelope

The art object.

Returns:: True if the art object is an envelope.

AIAPI AIErr(* AIEnvelopeSuite::MakeEnvelope)(AIArtHandle *art, ai::int32 numArt, AIArtHandle envelopeObject, AIEnvelopeOptions *options, AIArtHandle *envelope)

Creates an envelope for a given set of source art objects, or for the currently selected art if art is nullptr or numArt is 0.

By default, the new envelope is fully selected, and placed above the enveloped art object or objects in the paint order.

Parameters:

	art	An array of art objects to be enveloped, or `nullptr` to create an envelope for the current selection. Cannot be an art object stored in a dictionary, but can be the child of art stored in a dictionary.
	numArt	The number of objects in `art`, or 0 to create an envelope for the current selection.
	envelopeObject	The path art object to use as the new envelope, or `nullptr` to use the bounding box of `art` (or of the current selection) to create a new envelope object. (This would be the topmost selected object if you create the envelope using Object > Envelope Distort > Make with Top Object.)
	options	A pointer to the structure that specifies deformation options for the new envelope. Pass `nullptr` to use the default options, as specified by application preferences.
	envelope	[out] A buffer in which to return the new envelope object.

AIAPI AIErr(* AIEnvelopeSuite::ReleaseEnvelope)(AIArtHandle envelope)

Replaces an envelope in the document with its source contents (in the original, undistorted state) and a mesh object.

Moves both objects into the art tree, with the mesh object placed above the content object in the paint order. The content object is selected.

You cannot release envelopes stored directly in dictionaries, but you can release the children of envelopes stored in dictionaries.

Parameters:

envelope

The envelope object. Upon return, this reference is no longer valid.

AIAPI AIErr(* AIEnvelopeSuite::SetEnvelopeObject)(AIArtHandle envelope, AIArtHandle envelopeObject)

Sets the envelope object for an art group.

Parameters:

	envelope	The art group.
	envelopeObject	The envelope object, which must be of type `kPathArt` or `kMeshArt` and must not be directly stored in a dictionary.

AIAPI void(* AIEnvelopeSuite::SetEnvelopeOptions)(AIArtHandle envelope, AIEnvelopeOptions *options)

Sets the distortion options for an envelope.

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

Parameters:

	envelope	The envelope object.
	options	The new options structure,

AIAPI AIErr(* AIEnvelopeSuite::ToggleEditability)(AIArtHandle envelope)

Switches between editing the mesh and the contents of an envelope.

This is the same as choosing Object > Envelope Distort > Edit Contents or Object > Envelope Distort > Edit Envelope in the UI.

Parameters:

envelope

The envelope object.

See also:: EditingMesh(), EditingContents()

AIAPI AIErr(* AIEnvelopeSuite::UnconstrainedReshapePath)(const AIArtHandle inPath, const AIReal &param, const AIRealPoint &delta, bool shiftPressed)

Reshapes a path object.

Parameters:

	inPath	The path object.
	param	The t value for the curve from where the reshape is to be done.
	delta	The delta value that has to be translated to the path object.
	shiftPressed	If true, for straight line segments, the control handles are generated perpendicular to the segment. Otherwise, they are generated along the line segment.

AIAPI AIErr(* AIEnvelopeSuite::WarpEnvelope)(AIArtHandle envelope, AIWarpStyle warpStyle, AIReal bend, AIReal horizDistort, AIReal vertDistort, AIBoolean rotate90)

Redefines an envelope to use a predefined warp style.

The envelope must be in process of mesh-editing; that is, EditingMesh() would return true for envelope. Upon return the envelope is fully selected.

Parameters:

	envelope	The envelope object.
	warpStyle	The new warp style.
	bend	the new bend amount.
	horizDistort	The horizontal distortion amount.
	vertDistort	The vertical distortion amount.
	rotate90	When true, apply bend horizontally, when false, apply bend vertically.

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

AIEnvelope.h

AIEnvelopeSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIEnvelopeSuite Struct Reference
[API Suite List]