PainterInterface : ReferenceTarget

The Painter Interface is a general API introduced in 3ds Max 5 providing tools for painting on meshes. The functions and properties are accessible through an interface called thePainterInterface.

Defining Custom Paint Tools Using the Painter Interface

PainterInterface Interfaces

Interface: thePainterInterface

Properties:

.updateOnMouseUp : boolean : Read|Write

Get/Set the state of the "Update On Mouse Up" checkbox in the Painter Options dialog. When set to true, the Painter will update the stroke only when the mouse button is released.

.treeDepth : integer : Read|Write|Validated by Range: 2 to 10

Get/Set the depth of the quad tree used for hit testing. The larger the value, the faster the interaction, but more memory will be consumed and it will take longer to build the tree.

.minStr : float : Read|Write|Validated by Range: 0.0 to 1e+006

.maxStr : float : Read|Write|Validated by Range: 0.0 to 1e+006

Get/Set the Min. and Max. Strength values. If no pressure device is available, only the Max Strength is used.

.dragStrLimitMin : float : Read|Write

.dragStrLimitMax : float : Read|Write

These two values limit the Strenght range when using ALT-SHIFT drag to adjust the value interactively in the viewport.

.minSize : float : Read|Write|Validated by Range: 0.0 to 1e+006

.maxSize : float : Read|Write|Validated by Range: 0.0 to 1e+006

Get/Set the Brush Min. and Max. Size values. If no pressure device is available, only the Max Size is used.

.additiveMode : boolean : Read|Write

Get/Set the state of the "Additive" checkbox. When set to true, the painted values will add to the existing ones instead of overwriting them.

.drawRing : boolean : Read|Write

Get/Set the display of the Brush Ring.

.drawNormal : boolean : Read|Write

Get/Set the display of the Brush Normal vector.

.drawTrace : boolean : Read|Write

Get/Set the display of the Brush Trace line.

.normalScale : float : Read|Write

Get/Set the Normal Scale value.

.marker : float : Read|Write

Get/Set the Marker value .

.markerEnable : boolean : Read|Write

Enable/Disable the Marker.

.pressureEnable : boolean : Read|Write

Enable/Disable Pressure Sensitivity for use with pressure tablets.

.pressureAffects : integer : Read|Write|Validated by Range: 1 to 4

Get/Set the "Pressure Affects" option.

1 - None

2 - Strength

3 - Size

4 - Size and Strength

.predefinedStrEnable : boolean : Read|Write

Enable/Disable Predefined Strength Pressure. When set to true, instead of using the tablet pressure or Max Strength value, a graph is used to determine strength based on its position in the stroke. To set up the graph, you can use the options dialog to set up the "predefined pressure" properties. The options dialog is available via thePainterInterface.paintOptions()

.predefinedSizeEnable : boolean : Read|Write

Enable/Disable Predefined Size Pressure. When set to true, instead of using the tablet pressure or Max Size value, a graph is used to determine size based on its position in the stroke. To set up the graph, you can use the options dialog to set up the "predefined pressure" properties. The options dialog is available via thePainterInterface.paintOptions()

.mirrorEnable : boolean : Read|Write

Enable/Disable the Mirror option.

.mirrorAxis : integer : Read|Write|Validated by Range: 1 to 3

Get/Set the Mirror axis:

1 - X

2 - Y

3 - Z

.mirrorOffset : float : Read|Write|Validated by Range: -1e+006 to 1e+006

Get/Set the Mirror offset value.

.mirrorGizmoSize : float : Read|Write|Validated by Range: 0.0 to 1e+006

Get/Set the Mirror Gizmo size.

.pointGatherEnable : boolean : Read|Write

Enable/Disable the Point Gathering mode.

.buildNormals : boolean : Read|Write

Enable/Disable Normal building.

.offMeshHitType : integer : Read|Write

Defines the hit type for painting outside the mesh or without a mesh.

0 - creates a plane based on your last hit point and normal. When using this type there must be a mesh to paint on.

1 - a zdepth into the screen, this creates a plane x units into your view that you can paint on. No mesh is required in this case.

2 - create a plane on a point in world space aligned to the current view. No mesh is required in this case.

.offMeshHitZDepth : float : Read|Write

Defines the Z Depth to be used with offMeshHitType 1. (see above)

.offMeshHitPos : point3 : Read|Write

Defines the world position to be used with offMeshHitType 2. (see above)

Methods:

<void>initializeNodes <integer>flags <node array>nodeList

Initializes the nodes for painting. NodeList is an array of the nodes to paint on. Flags is currently not used, you can use 0 as stand-in.

<integer>numberNodes()

Returns the number of registered nodes.

<node>getNode <integer>index

Returns the indexed node.

<void>updateMeshes <boolean>updatePointGather

Updates the meshes. When the updatePointGather is supplied as true, the point gather list will be updated, too.

<void>startPaintSession()

Starts a Paint Session.

<void>endPaintSession()

Ends the Paint Session.

<void>paintOptions()

Opens the Paint Options dialog.

<void>macroCallback <string>macroName <string>category

Used to registers macro callback scripts to control the painting. macroName is the path to the macroScript source, category is the category of the macroScript.

<boolean>inPaintMode()

Returns true when in painting mode, false when painting is not active.

<boolean>getIsHit <integer>tabIndex

Returns true when the indexed point was a hit.

<void>getHitPointData <&point3>localHit <&point3>localNormal <&point3>worldHit <&point3>worldNormal <&float>radius <&float>str <integer>tabIndex

localHit is In and Out parameter

localNormal is In and Out parameter

worldHit is In and Out parameter

worldNormal is In and Out parameter

radius is In and Out parameter

str is In and Out parameter

The method lets you retrieve the hit point data of the stroke:

localHit is the hit position in local space of the node that was hit

localNormal is the normal of the face that was hit in local space of the node that was hit

worldHit is the world space hit point

worldNormal is the world space normal of the hit face

radius is the radius of the brush at the time of the hit

str is the strength of the brush at the time of the hit

tabIndex is the index of the hit point that you want to get. If this value is 0 it will return the last hit point.

 

<void>getHitFaceData <&point3>bary <&integer>faceIndex <node>node <integer>tabIndex

bary is In and Out parameter

faceIndex is In and Out parameter

This function lets you retrieve the hit face data of the stroke. This is the face data that exists at the top of the stack.

bary - the barycentric coords of the face that was hit

faceIndex - the index of the face that was hit

node - the node that was hit

tabIndex - this is the index of the hit point that you want to get If this value is 0 it will return the last hit point

 

<void>getHitPressureData <&boolean>shift <&boolean>ctrl <&boolean>alt <&float>pressure <integer>tabIndex

shift is In and Out parameter

ctrl is In and Out parameter

alt is In and Out parameter

pressure is In and Out parameter

This returns the key state and pressure state of a stroke point

shift is the state of the Shift key

ctrl is the state of the Ctrl key

alt is the state of the Alt key

pressure is the pressure from pressure sensitive tablets

tabIndex is this is the index of the hit point that you want to get. If this value is 0 it will return the last hit point.

 

<void>getMirrorHitPointData <&point3>localMirrorHit <&point3>localMirrorNormal <&point3>worldMirrorHit <&point3>worldMirrorNormal <integer>tabIndex

localMirrorHit is In and Out parameter

localMirrorNormal is In and Out parameter

worldMirrorHit is In and Out parameter

worldMirrorNormal is In and Out parameter

The method lets you retrieve the mirror hit point data of the stroke:

localMirrorHit is the mirror hit in local space of the node that was hit

localMirrorNormal is the normal of the face that was hit in local space of the node that was hit

worldMirrorHit is the world space hit point

worldMirrorNormal is the world space normal of the hit face

tabIndex is the index of the mirror hit point that you want to get. If this value is 0 it will return the last hit point.

 

<point2>getHitMousePos <integer>tabIndex

Returns the mouse position of the indexed hit point in the stroke.

<integer>getHitTime <integer>tabIndex

Returns the time of the indexed hit point in the stroke.

<float>getHitDist <integer>tabIndex

Returns the distance of the indexed hit point in the stroke.

<point3>getHitVec <integer>tabIndex

Returns the vector of the indexed hit point in the stroke.

<integer>getHitCount()

Returns the number of hits in the stroke.

<node>getHitNode <index>sampleIndex

Returns the hit node of the supplied sample index.

<void>loadCustomPointGather <node>node <point3 array>pointList

Loads a custom point list for the specified node.

<bitArray>getPointGatherHits <node>node

Returns the hit list as bitArray.

<point3>getPointGatherPoint <node>node <integer>index

Returns the position of the indexed point from the specified node.

<float>getPointGatherStr <node>node <integer>index

Returns the indexed point’s Strength from the specified node.

<float>getPointGatherWeight <node>node <integer>index

Returns the indexed point’s Weight from the specified node.

<point3>getPointGatherNormal <node>node <integer>index

Returns the indexed point’s Normal vector from the specified node.

<void>clearStroke()

Clears the stroke.

<void>addToStroke <point2>pos <boolean>updatePointGather <boolean>updateViewPort

Adds a point to the stroke. When updatePointGather is supplied as true, the point will be included in the list. When updateViewPort is supplied as true, the point will be displayed in the viewport.

<boolean>getRandomHitOnPoint <integer>index

Returns a random hit on the specified point.

<boolean>getRandomHitAlongStroke <integer>index

Returns a random hit along the specified stroke.

<boolean>getTestHit <point2>Point

Returns true if there is a hit at the specified point, false otherwise.

<void>getCustomHitPointData <&point3>localHit <&point3>localNormal <&point3>worldHit <&point3>worldNormal <&float>str

localHit is In and Out parameter

localNormal is In and Out parameter

worldHit is In and Out parameter

worldNormal is In and Out parameter

str is In and Out parameter

The method lets you retrieve custom hit point data:

localHit is the hit position in local space

localNormal is the normal of the face that was hit in local space

worldHit is the world space hit point

worldNormal is the world space normal of the hit face

str is the strength of the brush at the time of the hit

 

<void>getCustomHitFaceData <&point3>bary <&integer>faceIndex <node>node

bary is In and Out parameter

faceIndex is In and Out parameter

This function lets you retrieve the custom hit face data.

bary - the barycentric coordinates of the face that was hit

faceIndex - the index of the face that was hit

node - the node that was hit

 

<boolean>isPointInside <point2>testPoint <point2 array>pointList

Returns true if the specified testPoint is inside the polygon defined by the pointList coordinates.

<point3>getMirrorCenter()

Returns the center of the mirror gizmo.

<void>ScriptFunctions <value>startStroke <value>paintStroke <value>endStroke <value>cancelStroke <value>systemEnd

Registers MAXScript functions to be called by the Painter’s callback system at the specified events. See Defining Custom Paint Tools Using the Painter Interface for more details.

<void>undoStart()

Causes the undo system to start recording. It must be paired with an undoAccept or undoCancel. Typically called in the start of a stroke function.

<void>undoAccept()

Accepts the current state of the undo record and puts it on the undo stack. Typically called in in the end stroke function

<void>undoCancel()

Cancels the current undo record and restores the system to the state before the undoStart. Typically called in the stroke cancel function.

See also

Defining Custom Paint Tools Using the Painter Interface

PainterInterface - External Samples