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