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:

thePainterInterface.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.

   

thePainterInterface.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.

   

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

thePainterInterface.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.

   

thePainterInterface.dragStrLimitMin  : float : Read|Write

thePainterInterface.dragStrLimitMax : float : Read|Write 

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

   

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

thePainterInterface.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.

   

thePainterInterface.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.

   

thePainterInterface.drawRing : boolean : Read|Write 

Get/Set the display of the Brush Ring.

   

thePainterInterface.drawNormal : boolean : Read|Write 

Get/Set the display of the Brush Normal vector.

   

thePainterInterface.drawTrace : boolean : Read|Write 

Get/Set the display of the Brush Trace line.

   

thePainterInterface.normalScale : float : Read|Write 

Get/Set the Normal Scale value.

   

thePainterInterface.marker : float : Read|Write 

Get/Set the Marker value .

   

thePainterInterface.markerEnable : boolean : Read|Write 

Enable/Disable the Marker.

   

thePainterInterface.pressureEnable : boolean : Read|Write 

Enable/Disable Pressure Sensitivity for use with pressure tablets.

   

thePainterInterface.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

   

thePainterInterface.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()

   

thePainterInterface.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()

   

thePainterInterface.mirrorEnable : boolean : Read|Write 

Enable/Disable the Mirror option.

   

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

Get/Set the Mirror axis:

1 - X

2 - Y

3 - Z

   

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

Get/Set the Mirror offset value.

   

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

Get/Set the Mirror Gizmo size.

   

thePainterInterface.pointGatherEnable : boolean : Read|Write 

Enable/Disable the Point Gathering mode.

   

thePainterInterface.buildNormals : boolean : Read|Write 

Enable/Disable Normal building.

   

thePainterInterface.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.

   

thePainterInterface.offMeshHitZDepth : float : Read|Write 

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

   

thePainterInterface.offMeshHitPos : point3 : Read|Write 

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

Methods:

   

<void>thePainterInterface.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>thePainterInterface.numberNodes() 

Returns the number of registered nodes.

   

<node>thePainterInterface.getNode <integer>index 

Returns the indexed node.

   

<void>thePainterInterface.updateMeshes <boolean>updatePointGather 

Updates the meshes.

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

   

<void>thePainterInterface.startPaintSession() 

Starts a Paint Session.

   

<void>thePainterInterface.endPaintSession() 

Ends the Paint Session.

   

<void>thePainterInterface.paintOptions() 

Opens the Paint Options dialog.

   

<void>thePainterInterface.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>thePainterInterface.inPaintMode() 

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

   

<boolean>thePainterInterface.getIsHit <integer>tabIndex 

Returns true when the indexed point was a hit.

   

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

All parameters are in and out parameters.

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>thePainterInterface.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>thePainterInterface.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>thePainterInterface.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>thePainterInterface.getHitMousePos <integer>tabIndex 

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

   

<integer>thePainterInterface.getHitTime <integer>tabIndex 

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

   

<float>thePainterInterface.getHitDist <integer>tabIndex 

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

   

<point3>thePainterInterface.getHitVec <integer>tabIndex 

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

   

<integer>thePainterInterface.getHitCount() 

Returns the number of hits in the stroke.

   

<node>thePainterInterface.getHitNode <index>sampleIndex 

Returns the hit node of the supplied sample index.

   

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

Loads a custom point list for the specified node.

   

<bitArray>thePainterInterface.getPointGatherHits <node>node 

Returns the hit list as bitArray.

   

<point3>thePainterInterface.getPointGatherPoint <node>node <integer>index 

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

   

<float>thePainterInterface.getPointGatherStr <node>node <integer>index 

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

   

<float>thePainterInterface.getPointGatherWeight <node>node <integer>index 

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

   

<point3>thePainterInterface.getPointGatherNormal <node>node <integer>index 

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

   

<void>thePainterInterface.clearStroke() 

Clears the stroke.

   

<void>thePainterInterface.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>thePainterInterface.getRandomHitOnPoint <integer>index 

Returns a random hit on the specified point.

   

<boolean>thePainterInterface.getRandomHitAlongStroke <integer>index 

Returns a random hit along the specified stroke.

   

<boolean>thePainterInterface.getTestHit <point2>Point 

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

   

<void>thePainterInterface.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>thePainterInterface.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>thePainterInterface.isPointInside <point2>testPoint <point2 array>pointList 

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

   

<point3>thePainterInterface.getMirrorCenter() 

Returns the center of the mirror gizmo.

   

<void>thePainterInterface.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>thePainterInterface.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>thePainterInterface.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>thePainterInterface.undoCancel() 

See Also