AIBeautifulStrokes.h File Reference

#include "AITypes.h"
#include "AIEntry.h"
#include "AILiveEffect.h"
#include "AITabletData.h"
#include "AIPath.h"
#include "AIHeaderBegin.h"
#include "AIHeaderEnd.h"

Go to the source code of this file.

Classes
struct	StrokeHitResults
	Filled out by AIBeautifulStrokesSuite::StrokeHitTest(), to report the results of a hit test on the focal stroke of a given path. More...
struct	PathEditDescription
	The details of an edit description, passed as a parameter to AIBeautifulStrokesSuite::AdjustWidthAnchorsBeforePathEdit(). More...
struct	AIBeautifulStrokesSuite
	This suite allows you to control advanced features for stroking paths. More...
Defines
#define	kAIBeautifulStrokesSuite   "AI Beautiful Strokes Suite"
#define	kAIBeautifulStrokesSuiteVersion3   AIAPI_VERSION(3)
#define	kAIBeautifulStrokesSuiteVersion   kAIBeautifulStrokesSuiteVersion3
#define	kAIBeautifulStrokesVersion   kAIBeautifulStrokesSuiteVersion
#define	kAIBeautifulStrokesParamsDictKey   "kAIBeautifulStrokesParamsDictKey"
	Dictionary key for the Beautiful Strokes dictionary inside an AILiveEffectParameters dictionary.
Typedefs
typedef ai::uint32	WidthMarkerFlags
	See WidthMarkerFlagValues.
typedef AIAPI AIBoolean(*	AIGenerateArtProgressProc )(ai::int32 current, ai::int32 total)
	Callback for progress reports during a call to AIBeautifulStrokeSuite::GenerateArt().
Enumerations
enum	RepeatedArtAdjustment {   kStretch, kAddSpace, kAdjustPath, kUnknownRepeatedArtAdjustment = 0xFFFFFFFF,   RepeatedArtAdjustment_dummy = 0xFFFFFFFF }
	Constants for AIBeautifulStrokesSuite::SetArtPatternPaint() and /c AIBeautifulStrokesSuite::GetArtPatternPaint() that determine how to apply art along a path. More...
enum	RepeatedArtCorner {   kNoCorner, kAutoCentered, kAutoBetween, kAutoSliced,   kAutoOverlap }
enum	StrokeWidthSource {   kConstantWidth, kTabletData, kUserProfile, kCenteredProfileMark = 0x0000FF01,   kUncenteredProfileMark, kCenteredProfileInterpolation, kUncenteredProfileInterpolation, kUnknownStrokeWidthSource = 0xFFFFFFFF,   StrokeWidthSource_dummy = 0xFFFFFFFF }
	Constants for AIBeautifulStrokesSuite functions that set stroke widths. More...
enum	GradientStrokeApplication { kGradientStrokeMask, kGradientStrokeAlong, kGradientStrokeAcross, kGradientStroke_dummy = 0xFFFFFFFF }
enum	ArrowTipAlignment { kArrowTipAtEnd, kArrowAttachmentPtAtEnd, kArrowTruncationPtAtEnd, kUnknownArrowAlignment = 0xFFFFFFFF }
	Constants for AIBeautifulStrokesSuite::SetArrowheadOptions() that determine how to position the arrows at the ends of the path. More...
enum	WidthMarkerFlagValues {   kNoWidthMarkerFlags = 0, kIncomingWidthMarker = 0x1, kOutgoingWidthMarker = 0x4, kCornerWidthMarker = 0x10,   kCornerLeftWidthMarker = 0x10, kCornerRightWidthMarker = 0x20, kAnchoredWidthMarker = 0x40, kSpreadWidthChanges = 0x10000,   kCopyMarker = 0x20000, kLimitAtNeighbors = 0x40000, kUniformChangeAcrossSpread = 0x80000, kProportionalChangeAcrossSpread = 0x100000 }
enum	PathEditType {   kClearProfileAnchorsOnly = 0, kClearAnchorsAndResetProfile, kCopyAndResetAnchors, kTranslate1Anchor,   kRemove1Anchor, kAdd1Anchor, kAdjustBezier, kTransformSelection,   kReversePathDirection, kSplitPath, kApplyStyle }
	An overview of the kind of path edit being performed, included as part of a PathEditDescription. More...

---

Define Documentation

#define kAIBeautifulStrokesSuite   "AI Beautiful Strokes Suite"

#define kAIBeautifulStrokesSuiteVersion   kAIBeautifulStrokesSuiteVersion3

#define kAIBeautifulStrokesSuiteVersion3   AIAPI_VERSION(3)

#define kAIBeautifulStrokesVersion   kAIBeautifulStrokesSuiteVersion

---

Typedef Documentation

typedef AIAPI AIBoolean(* AIGenerateArtProgressProc)(ai::int32 current, ai::int32 total)

Callback for progress reports during a call to AIBeautifulStrokeSuite::GenerateArt().

Parameters:

	current	The current progress, a value between 0 and total. Always equal to 0 currently.
	total	A value at which the operation is complete. Always equal to 1 currently.

Returns:

False if user cancels the operation, otherwise true.

typedef ai::uint32 WidthMarkerFlags

See WidthMarkerFlagValues.

A logical OR of WidthMarkerFlagValues. */.

---

Enumeration Type Documentation

enum ArrowTipAlignment

Constants for AIBeautifulStrokesSuite::SetArrowheadOptions() that determine how to position the arrows at the ends of the path.

Enumerator:

kArrowTipAtEnd	Put the tip of the arrow at the end of the path. The attachment point is placed on the path, and the path then cut at the truncation point.
kArrowAttachmentPtAtEnd	Put the attachment point of the arrow at the end of the path. The line between the attachment point and the tip is aligned with the path's tangent at that end.
kArrowTruncationPtAtEnd	Put the truncation point of the arrow at the end of the path. The line between the truncation point and the tip is aligned with the path's tangent at that end.
kUnknownArrowAlignment	Special return value to indicate mixed values when the params dict represents an accumulation of the values from multiple objects, such as returned by AIPathStyleSuite::GetCurrentPathStyle(). Passing this in as a value to "set" in a params dictionary means that the existing value, if any, should not change.

enum GradientStrokeApplication

Enumerator:

kGradientStrokeMask	Use the stroke to mask the gradient as if the stroke were outlined and filled (default).
kGradientStrokeAlong	Apply the gradient along the length of the stroke.
kGradientStrokeAcross	Apply the gradient across the width of the stroke.
kGradientStroke_dummy	Dummy value to ensure 32-bit enum value size.

enum PathEditType

An overview of the kind of path edit being performed, included as part of a PathEditDescription.

Enumerator:

kClearProfileAnchorsOnly	Remove any width profile anchors from the path, but do not modify the art style.
kClearAnchorsAndResetProfile	Remove any width profile anchors from the path, and apply a new art style in which the width profile distances have been reset to their values according to the current path distance. This is appropriate when a path is about to be edited in a way that keeps the path distances roughly the same proportionally, but changes the number of anchor points in a way that is too complex to attempt moving the anchors to new indexes, such as Offset Path or Simplify. See also kCopyAndResetAnchors, below.
kCopyAndResetAnchors	Transfer any profile anchors from the source path in the PathEditDescription onto the art dictionary of the path, copying them exactly if the number of segments on the two paths are the same and they are either both open or both closed, otherwise resetting the profile anchors so that they maintain approximately the same fractional path distances, but are relative to the segment indices of the new path. This is an alternative to kClearAnchorsAndResetProfile, for situations where the destination path is a duplicate or a modified duplicate of the source path, especially useful for contexts where the path being modified is an input path to an effect under execution, and hence has been stripped of its paint. The art style of the path is not modified.
kTranslate1Anchor	A single anchor point (which may or may not be selected) is about to be moved.
kRemove1Anchor	A single anchor point (which may or may not be selected) is about to be removed, while preserving the path continuity (that is, the path is not split).
kAdd1Anchor	A single anchor point is about to be added.
kAdjustBezier	A bezier segment is about to be adjusted, while leaving the bounding anchor points alone.
kTransformSelection	The selected components of the path are about to be transformed. It is not necessary to notify of this if the transformation preserves relative distances between anchor points, such as a rotation, translation, or uniform scale of a fully selected path. Should be notified if either the path is partially selected, or the transformation changes the relative lengths of bezier segments, such as a shear or non-uniform scale.
kReversePathDirection	The anchor points of the path are about to be reversed.
kSplitPath	A new path has been constructed from a portion of another path (with, for instance, Delete, Copy, or Scissor on a partially selected path). For this type of edit, the path parameter to AIBeautifulStrokesSuite::AdjustWidthAnchorsBeforePathEdit() should be the new path; the original path is passed as the source path in the PathEditDescription.
kApplyStyle	A new art style is about to be applied to the path .

enum RepeatedArtAdjustment

Constants for AIBeautifulStrokesSuite::SetArtPatternPaint() and /c AIBeautifulStrokesSuite::GetArtPatternPaint() that determine how to apply art along a path.

Enumerator:

kStretch	Stretch art to fit path.
kAddSpace	Add space between art to fit path.
kAdjustPath	Adjust length of path to fit art.
kUnknownRepeatedArtAdjustment	Special return value to indicate mixed values when the params dict represents an accumulation of the values from multiple objects, such as returned by AIPathStyleSuite::GetCurrentPathStyle(). Passing this in as a value to "set" in a params dictionary means that the existing value, if any, should not change.
RepeatedArtAdjustment_dummy	Dummy value to ensure 32-bit enum value size.

enum RepeatedArtCorner

Enumerator:

kNoCorner	For not using an Auto Generated Corner.
kAutoCentered	Creates a corner centered around the border/side tile.
kAutoBetween	Creates a corner by cutting the border/side tile into 2 halves.
kAutoSliced	Creates a corner by slicing the border/side tile.
kAutoOverlap	Creates a corner by overlapping the border/side tile.

enum StrokeWidthSource

Constants for AIBeautifulStrokesSuite functions that set stroke widths.

The first three values are used to set the stroke width source for an entire path or Beautiful Strokes dictionary. The "centered" values further specify the source of a requested width at a specific location on a path, as returned by AIBeautifulStrokesSuite::GetWidthsAtDistance() and parallel functions.

Enumerator:

kConstantWidth	Use a constant width derived from the AIPathStyle stroke width setting.
kTabletData	Use width from tablet data; set specific channel with AIBeautifulStrokesSuite::SetWidthTabletDataSource().
kUserProfile	Use variable width from user-provided profile. See AIBeautifulStrokesSuite::SetCenteredWidthProfile() and AIBeautifulStrokesSuite::SetUncenteredWidthProfile().
kCenteredProfileMark	Get width from this location on the path.
kUncenteredProfileMark	Get width from this location on the path.
kCenteredProfileInterpolation	Get width from this location on the path.
kUncenteredProfileInterpolation	Get width from this location on the path.
kUnknownStrokeWidthSource	Special return value to indicate mixed values when the params dict represents an accumulation of the values from multiple objects, such as returned by AIPathStyleSuite::GetCurrentPathStyle(). Passing this in as a value to "set" in a params dictionary means that that the existing value, if any, should not change.
StrokeWidthSource_dummy	Dummy value to ensure 32-bit enum value size.

enum WidthMarkerFlagValues

Enumerator:

kNoWidthMarkerFlags	No flags set.
kIncomingWidthMarker	The marker indicates the incoming width only, that is, it is the width for interpolating to the previous marker. The next marker should be an outgoing width only, and is typically a different width value on at least one side of the stroke. If passed to a width-changing function, indicates that only the incoming width at that t value should be changed, with the outgoing width staying the same.
kOutgoingWidthMarker	The marker indicates the outgoing width only, that is, it is the width for interpolating to the next marker. The previous marker should be an incoming width only, and is typically a different width value. If passed to a width-changing function, indicates that only the outgoing width at that t value should be changed, with the incoming width staying the same.
kCornerWidthMarker	The width at the indicated point forms a corner; that is, if the adjacent markers are at a different width, it starts interpolating linearly to the adjacent value, rather than spreading smoothly.
kCornerLeftWidthMarker	If the width is uncentered, set the corner vs smooth attribute separately for the left width.
kCornerRightWidthMarker	If the width is uncentered, set the corner vs smooth attribute separately for the right width.
kAnchoredWidthMarker	The width marker at the indicated point prefers to be tied to a position on the path expressed as as an anchor point index, rather than being placed at the t value in the t values array. Width profiles can be shared by multiple paths, since they are part of art style definitions, and multiple paths can carry the same art style. So the actual profile contains only the flags that say which of the width marks should be shifted to the anchored places, if they exist on the path to which it is applied. The paths then in turn carry data that records which of the positions on the path want to have width markers anchored to them. For example, if there are three interior width markers in the profile that prefer to be tied to anchor points, and only one interior anchor point on a path to which that profile is applied, then not all the anchor requests can be honored. When a width profile contains anchored width marks, the t values are adjusted when the stroke is generated, so that the widths at those marks move to the anchor positions, and any unanchored width markers between them are shifted proportionally. (The first and last width mark in a profile are always anchored respectively to the start and end of the path, so this flag is ignored for those width marks.) Left and right widths must always be anchored together, as must incoming and outgoing width markers, since the left and right markers share the same tValues array and are always at the same offsets along the path.
kSpreadWidthChanges	When passed to functions that take an art object and modify the width at a given t value, propagate the changes across multiple adjacent markers. Scope depends on selection state, and by default is bounded by corner points. If not set, only the width at the given t value changes, and all other markers stay the same. The way the changes propagate can be modified by setting kUniformChangeAcrossSpread or kProportionalChangeAcrossSpread. If both are off, the amount of change tapers down logarithmically with distance from the t value at which the change is specified, until it reaches 0 at the ends of the spread.
kCopyMarker	When passed to AIBeautifulStrokesSuite::SlideWidthMarkerToNewT(), specifies that the marker should be duplicated and the new marker dragged while the old one is left behind.
kLimitAtNeighbors	When passed to AIBeautifulStrokesSuite::SlideWidthMarkerToNewT(), specifies that markers are not allowed to move past adjacent ones. Ignored if kSpreadWidthChanges is also on.
kUniformChangeAcrossSpread	Refines the meaning of kSpreadWidthChanges; ignored if that flag is off. If on, the same offset is added or subtracted from all other markers in the affected spread, subject to remaining in the valid range.
kProportionalChangeAcrossSpread	Refines the meaning of kSpreadWidthChanges; ignored if that flag is off. If on, and kUniformChangeAcrossSpread is off, other markers in the affected spread change by the same proportion that the one being directly modified does. For example, if the width at the directly modified t value is doubled, then all other widths in the affected spread are doubled.