pmodel (lx_pmodel.hpp)

From The Foundry MODO SDK wiki
Jump to: navigation, search
There are security restrictions on this page


Mesh Operation Item

Item Type

The procedural modeling system works by evaluating a series of mesh operations, on a target mesh, to result in a final modified mesh. To integrate a mesh operation interface into the procedural modeling system, the mesh operations need to be associated with an item, that can be managed by the user. The mesh operation item performs this duty. It contains a MeshOpObj channel which stores the mesh operation, and is evaluated by the procedural modeling system, to perform an edit to the mesh.

Mesh Operation items all derive from a common type. This type is extremely basic and has no transforms or position in 3D space. There are four default channels on every Mesh Operation Item, defining things like selection type and the enable state.

(1) SDK: Declarations
 #define LXsITYPE_MESHOP                 "meshoperation"
 #define LXsICHAN_MESHOP_ENABLE          "enable"
 #define LXsICHAN_MESHOP_OBJ             "meshOpObj"
 #define LXsICHAN_MESHOP_SELTYPE         "selectionType"

The custom creation command allows a custom command to be fired to handle the creation of the mesh operation item. This is useful if additional setup is required, that is unique to a specific mesh operation item.

(2) SDK: Declarations
 #define LXsPKG_MESHOP_CREATECMD         "meshop.create"

Automatic Conversion

The steps to manually implement a Mesh Operation item can be quite complex. Because of this, a simpler method is provided, allowing ILxMeshOperation interfaces to be automatically converted into Mesh Operation items. This is only useful for simple mesh operations, that simply take a mesh, modify it and return a modified mesh, using nothing more than a few simple attributes.

Applying the following server tag to an ILxMeshOperation interface, will automatically create a mesh operation item and a modifier, writing the mesh operation server into a channel, so that it can be evaluated as part of the procedural system. The Mesh Operation server being converted, should also implement an Attributes interface. The attributes will be automatically converted into channels on the newly created item. The value of this tag doesn't matter, as the presence of the server tag is enough to automatically create a mesh operation item.

(3) SDK: Declarations
 #define LXsMESHOP_PMODEL                "pmodel.meshop"

Manual Implementation

For more complex mesh operations, it is suggested that a Mesh Operation Item be implemented manually. This will allow full control over the channels on the Mesh Operation item, as well as allowing more complex channel data types, and also Mesh Operations that depend on other items in the scene.

To implement a Mesh Operation manually, a package should be created with a superType of LXsITYPE_MESHOP. This will automatically provide it with a Mesh graph input, and the standard set of channels, common to all Mesh Operation item types. A modifier should read the various input channels required to evaluate the Mesh Operation, it should spawn an ILxMeshOperation interface, and store it in the LXsICHAN_MESHOP_OBJ channel on the Mesh Operation item.

Tool Operation Item

Tool Operation Items allow traditional modeling tools that perform an edit to a mesh, to integrate into the procedural system as items. Tool Handles implemented on a Tool Model interface, will automatically be displayed when an item of this type is selected, and sub-tools such as snapping, symmetry and the workplane, can be used to directly modify a tools behavior.

The "tool" graph is automatically added to any tool operation item that performs an "actor" task. It is used to connect non-actor tools into the actor tool to create a mini-toolpipe. This mini tool pipe is evaluated, allowing the behavior of an actor tool to be modified.

(4) SDK: Declarations
 #define LXsGRAPH_TOOL                   "tool"

Tool Operation items all derive from a common type, which it itself a sub-type of the Mesh Operation item type.

(5) SDK: Declarations
 #define LXsITYPE_TOOLOP                 "tooloperation"

This function returns the Procedural Modeling Tool graph.

(6) PUB: PModelToolGraph usage
         HyGraphID
 PModelToolGraph (
         CinemaID                 cinema)

This function populates an ordered array with the items connected to a particular item in the Procedural Modeling tool graph. The return value is the number of items stored in the ordered array.

(7) PUB: PModelToolGraphCollectItems usage
         int
 PModelToolGraphCollectItems (
         CineItemID               item,
         OrderedArray            *list,
         int                      fwd)

This function returns the task that a tool operation performs. This is one of the LXi_TASK defines.

(8) PUB: PModelToolTask usage
         ID4
 PModelToolTask (
         CineItemID               item)

This function returns the task that a tool operation type performs. This is one of the LXi_TASK defines.

(9) PUB: PModelToolTypeTask usage
         ID4
 PModelToolTypeTask (
         int                      type)

This function tests if a tool operation is an actor. If a tool operation is an actor, it performs edits to geometry.

(10) PUB: PModelToolIsActor usage
         int
 PModelToolIsActor (
         CineItemID               item)

This function tests if a tool operation type is an actor. If a tool operation is an actor, it performs edits to geometry.

(11) PUB: PModelToolTypeIsActor usage
         int
 PModelToolTypeIsActor (
         int                      type)

Automatic Conversion

There are a number of similarities between procedural mesh operations and traditional tools that operate on meshes. Rather than implementing a tool for one context and a mesh operation for another context, it is often desirable to implement functionality once and use in both contexts. As we have a large library of existing tools, converting a tool to work with the procedural modeling system needs to be quick and painless.

Adding the following server tag to an ILxTool server, will automatically convert the tool into a Tool Operation Item, that can be integrated directly into the procedural modeling system. The value of this tag doesn't matter, as the presence of the server tag is enough to convert the tool to work with the procedural modeling system.

(12) SDK: Declarations
 #define LXsTOOL_PMODEL                  "pmodel.toolop"

Whilst the addition of the server tag makes it simple to convert an existing tool to work with the procedural modeling system, more work is often needed to the tool itself, to ensure it works correctly in an evaluated context. The tool should implement a GetOp function that spawns and returns a Tool Operation interface.

Some considerations also need to be made to the evaluation of the tool operation. The general rule is that when evaluated procedurally, a tool should not rely on any global state, or values that aren't provided by either tool attributes or tool packets. It should not attempt any operation that requires an undo context or attempt to execute commands. With some thought and design, it should be possible to convert most tools that operate on meshes, to work in a procedural context, without altering the functionality of the tool itself.

On automatically generated tool operation items, the tool object will be stored in the following channel.

(13) SDK: Declarations
 #define LXsICHAN_TOOL_OBJ               "toolObj"

Manual Implementation

Whilst it's often desirable to automatically generate a Tool Operation item from an existing tool, it is also possible to manually implement Tool Operation items that can be integrated into the procedural system. This is useful for writing tool operation items that provide more complexity than is usually supported through the tool system.

To create a Tool Operation Item from scratch. A package should be created, with a SuperType of LXsITYPE_TOOLOP. This will provide it with the standard set of channels, common to all Tool Operation items.

A Modifier, associated with the Tool Operation Item, should read any channels it requires to evaluate the tool. It should spawn an ILxTool interface and write it into a channel on the package of the type LXsTYPE_OBJREF. The channel name used for storing the tool, should be defined on the server tags using the following tag.

(14) SDK: Declarations
 #define LXsPKG_TOOL_CHANNEL             "tool.channel"

Two other server tags should also be added to the package. One defines the task of the tool, and should be of the type LXs_TASK and the other defines the order of evaluation and should be LXs_ORD. In the majority of cases, these values should be identical to the values returned by the tool.

(15) SDK: Declarations
 #define LXsPKG_TOOL_TASK                "tool.task"
 #define LXsPKG_TOOL_ORDER               "tool.order"

Selection Operation Item

The selection operation item provides a selection range over which a mesh operation will operate. It contains a SelOpObj channel which stores the selection operation, and is evaluated by the procedural modeling system, to mark the active selection prior to mesh op evaluation.

Selection Operation items all derive from a common type. This type is extremely basic and has no transforms or position in 3D space. The default channels define the enable state, and the output channel to which the ILxSelectionID is written.

Item Type

(16) SDK: Declarations
 #define LXsGRAPH_SELOP                  "selop"

(17) SDK: Declarations
 #define LXsITYPE_SELOP                  "selectionoperation"
 
 #define LXsICHAN_SELOP_ENABLE           "enable"
 #define LXsICHAN_SELOP_OBJ              "selopobj"

Selection Operations should specify the types of selection they support. Mesh Operation and Tool Operation items should also specify the type of selections they require. This combination of selection types on both the selection operation and the mesh operation, helps determine which selection operations can be used with which mesh operations.

Supported selection types are defined using the following server tag. The server is expected to provide a comma seperated list of selection types. The server can also specify that no selection is required by returning the NONE value. If no tag is provided, it will be assumed that all types are supported.

(18) SDK: Declarations
 #define LXsPMODEL_SELECTIONTYPES        "selectionoperation"

The server tag must have one of the following values. Any other value will be treated as supporting all selection types.

(19) SDK: Declarations
 #define LXsSELOP_TYPE_NONE              "-"
 #define LXsSELOP_TYPE_VERTEX            "VERX"
 #define LXsSELOP_TYPE_EDGE              "EDGE"
 #define LXsSELOP_TYPE_POLYGON           "POLY"

Automatic Conversion

The steps to manually implement a Selection Operation item can be quite complex. Because of this, a simpler method is provided, allowing ILxSelectionOperation interfaces to be automatically converted into Selection Operation items. This is only useful for simple selection operations, that can test the selection status of an element without any complex channel input->

Applying the following server tag to an ILxSelectionOperation interface, will automatically create a selection operation item and a modifier, writing the Selection operation server into a channel, so that it can be queried as part of the procedural system. The Selection Operation server being converted, should also implement an Attributes interface. The attributes will be automatically converted into channels on the newly created item. The value of this tag doesn't matter, as the presence of the server tag is enough to automatically create a selection operation item.

(20) SDK: Declarations
 #define LXsSELOP_PMODEL                 "pmodel.selectionop"

Selection Operation Interface

This interface allows the procedural modeling system to test the selection status of a given element, allowing it to mark it for use during mesh operation evaluation.

(21) SDK: Declarations
 #define LXu_SELECTIONOPERATION          "563E56B1-ACC9-4E3F-B3A8-E0AFE2AB5645"
 #define LXa_SELECTIONOPERATION          "selectionoperation"

This function is called before any elements are tested, to set the mesh that the elements belong to.

(22) SDK: ILxSelectionOperation interface
         LXxMETHOD( LxResult,
 SetMesh) (
         LXtObjectID              self,
         LXtObjectID              mesh);

This function is called before any elements are tested. It provides the transform matrix for the mesh being tested. It can then be used for transforming any component position tests into world space.

(23) SDK: ILxSelectionOperation interface
         LXxMETHOD( LxResult,
 SetTransform) (
         LXtObjectID              self,
         LXtMatrix4               xfrm);

This method returns either LXe_TRUE or LXe_FALSE, indicating whether or not the given point should be included in the selection.

(24) SDK: ILxSelectionOperation interface
         LXxMETHOD( LxResult,
 TestPoint) (
         LXtObjectID              self,
         LXtPointID               point);

This method returns either LXe_TRUE or LXe_FALSE, indicating whether or not the given edge should be included in the selection.

(25) SDK: ILxSelectionOperation interface
         LXxMETHOD( LxResult,
 TestEdge) (
         LXtObjectID              self,
         LXtEdgeID                edge);

This method returns either LXe_TRUE or LXe_FALSE, indicating whether or not the given polygon should be included in the selection.

(26) SDK: ILxSelectionOperation interface
         LXxMETHOD( LxResult,
 TestPolygon) (
         LXtObjectID              self,
         LXtPolygonID             polygon);

(27) User Class: SelectionOperation method

Empty Mesh Operation Python user class.

(28) PY: SelectionOperation method
 pass