predest (lx_predest.hpp)

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


Contents

(Shader Tree) Item Presets

Item presets are .LXP (IFF LXPR) files that require a destination item and/or scene to apply themselves, usually somewhere in a shader tree. The presets store a primary item, and possibly also linked or child items. Their destination requirements are identified based on the type of the primary item, which will typically be a material item, or a group/mask item with material, texture(s), etc.

(1) SDK: LXu_SHADERPREDEST, etc. defines
 #define LXu_SHADERPREDEST               "51CE68B9-BDED-41FC-BD33-37BBAFFD180B"
 #define LXa_SHADERPREDEST               "shaderPresetDestination"

ILxShaderPreDest Definition

The shader preset may need a scene to load into, if it was no item is directly applicable. In this case, the contents of the preset will simply be added to the scene.

(2) SDK: ShaderPreDest::Scene
         LXxMETHOD( LxResult,
 Scene) (
         LXtObjectID               self,
         void                    **ppvObj);

The destination item will 'receive' the preset, and either have some channels changed, or have some items added as children, or possibly, have its children all killed, and replaced by new children that it must love just as much. The mode argument gives the loader's Apply method a hint about how to treat the destination content.

(3) SDK: ShaderPreDest::Item
         LXxMETHOD( LxResult,
 Item) (
         LXtObjectID               self,
         int                      *mode,
         void                    **ppvObj);

This method returns the parent or container for the the destination item. In most cases, this is simply the scene's render item, and if this method returns NOT_IMPLEMENTED, the client can just find the first render item in the scene, as so much other code does. It will often be useful however, to provide a container group for the preset. In the case of a material preset, this could specify the group into which the material should be added, (though the Item should have returned a material in this group...). For a group preset, the group would be added inside the container, which will let a preset import be encapsulated by the client.

(4) SDK: ShaderPreDest::ContainerItem
         LXxMETHOD( LxResult,
 ContainerItem) (
         LXtObjectID               self,
         void                    **ppvObj);

This method returns the geometry item the preset was dropped on. This may be NULL if the preset wasn't dropped on actual geometry.

(5) SDK: ShaderPreDest::HitItem
         LXxMETHOD( LxResult,
 HitItem) (
         LXtObjectID               self,
         void                    **ppvObj);

This method allows the client to read tags defining the surface being shaded. This can be useful for positioning some more complex shading presets.

(6) SDK: ShaderPreDest::GetTag
         LXxMETHOD( LxResult,
 GetTag) (
         LXtObjectID              self,
         LXtID4                   type,
         const char             **tag);

This method returns the preset mode either add or apply.

(7) SDK: ShaderPreDest::Mode
         LXxMETHOD( LxResult,
 Mode) (
         LXtObjectID              self,
         int                     *mode);

(8) SDK: empty ShaderPreDest User Class

Empty ShaderPreDest Python user class.

(9) PY: empty ShaderPreDest user class
 pass

Mesh Layer Presets

At this point the vague consensus serving as a design indicates mesh presets will be single layer mesh information, along with the necessary materials. (we will ignore for a moment the completely open-ended nature of this requirement, given the potential dependency of shading a single poly on the entire scene graph.) All that we need for a mesh preset destination, besides a potentially infinite bit of the shader tree, is a mesh. While it has been suggested that the destination should also supply a transformation for the mesh elements, this does not make sense in the driving scenario of meshpaint, since each painted mesh will need a different transform. If the transform is built into the destination, it implies that each painted clone will be reloaded from disk individually. Further, existing tools that use mesh layers (booleans, meshpaint, etc) expect to work with a source mesh, and little else. Nevertheless, a transform may be specified, for a initial transformation. Clients which will be duplicating the mesh with different transforms are expected to hold the mesh themselves, rather than reloading it, and transform the copies as needed.

(10) SDK: LXu_MESHLAYERPREDEST, etc. defines
 #define LXu_MESHLAYERPREDEST    "052B08CD-F2F2-4C0F-9D32-1AAFEF494D36"
 #define LXa_MESHLAYERPREDEST    "meshPresetDestination"

ILxMeshLayerPreDest Definition

The mesh layer preset needs an existing mesh to load into (what else?). This method returns the destination mesh. It may be a current user mesh, or it may be a newly created 'template' mesh which will then be used like a BG layer for cloning, booleans, etc.

(11) SDK: MeshLayerPreDest::Mesh
         LXxMETHOD( LxResult,
 Mesh) (
         LXtObjectID               self,
         void                    **ppvObj);

For false convenience, and to adhere to the fascination with bloated, lossy homogeneous matrices for passing transformations around, the desired transformation of the mesh elements as they are placed in the mesh is returned in an LXtMatrix4 by this function. If this function returns not implemented, no transformation is applied.

(12) SDK: MeshLayerPreDest::Transform
         LXxMETHOD( LxResult,
 Transform) (
         LXtObjectID              self,
         LXtMatrix4               xform);

(13) SDK: LXSHPRE_MODEi_ADD, etc. defines

To facilitate the loading of a mesh layer's various shader tree components, we will simply demand a shader tree destination object.

(14) SDK: MeshLayerPreDest::ShaderDest
         LXxMETHOD( LxResult,
 ShaderDest) (
         LXtObjectID               self,
         void                    **ppvObj);

(15) SDK: empty MeshLayerPreDest User Class

Empty MeshLayerPreDest Python user class.

(16) PY: empty MeshLayerPreDest user class
 pass

Scene Item Presets

Destination requirements for a general item preset seem, based on the current vague consensus of what an item preset does, to be similar to tha shader destination; there is possibly a target item, or there might be an item that should become the parent, and there is almost certainly a scene. Thus for efficiency we can start of with an identical interface, and see where it goes as requirements are first defined then refined.

(17) SDK: LXu_SCENEITEMPREDEST, etc. defines
 #define LXu_SCENEITEMPREDEST            "F81AD9DB-6068-4782-B1BB-7F45233682DC"
 #define LXa_SCENEITEMPREDEST            "sceneItemPresetDestination"

ILxSceneItemPreDest Definition

Return the ILxScene

(18) SDK: SceneItemPreDest::Scene
         LXxMETHOD( LxResult,
 Scene) (
         LXtObjectID               self,
         void                    **ppvObj);

This is the target item, presumably the same type as the preset, that will have channels replaced by the incoming item's channels.. or whatever. It can be null to just add a new item from the preset to the scene.

(19) SDK: SceneItemPreDest::Item
         LXxMETHOD( LxResult,
 Item) (
         LXtObjectID               self,
         int                      *mode,
         void                    **ppvObj);

This method returns the parent or container for the the destination item.

(20) SDK: SceneItemPreDest::ContainerItem
         LXxMETHOD( LxResult,
 ContainerItem) (
         LXtObjectID               self,
         void                    **ppvObj);

This method returns a position at which to place the item, if it has been set, or LXe_FAIL otherwise

(21) SDK: SceneItemPreDest::Position
         LXxMETHOD( LxResult,
 Position) (
         LXtObjectID               self,
         LXtVector                 pos);

This method returns an orientation for the item, if it has been set, or LXe_FAIL otherwise. The orientation is stored in a matrix to assure that no useful information can be retrieved from it and rotations are clipped to 1 cycle.

(22) SDK: SceneItemPreDest::Orientation
         LXxMETHOD( LxResult,
 Orientation) (
         LXtObjectID               self,
         LXtMatrix                 xfrm);

(23) SDK: empty SceneItemPreDest User Class

Empty SceneItemPreDest Python user class.

(24) PY: empty SceneItemPreDest user class
 pass

Photometry Presets

(25) SDK: LXu_PHOTOMETRYPREDEST, etc. defines
 #define LXu_PHOTOMETRYPREDEST           "C64CB56A-16EA-4B4D-96EC-B6911459103A"
 #define LXa_PHOTOMETRYPREDEST           "photometryPresetDestination"

Photometry presets are presets for IES/EULUMDAT lights. The destination interface is identical to that for Scene Item presets, but they require a different GUID to be handled differently (I think). The files are loaded just like normal images, but can be distinguished by the "LightMap.Lumens" image attribute set by the loader. When the appropriate loader recognizes the file, it can be applied to an existing light, or added to a freshly created light.

Profile Presets

Profile presets store a geometry pattern used with modeling tools. There are two types of profile.

(26) SDK: LXu_PROFILE1DPREDEST, etc. defines
 #define LXu_PROFILE1DPREDEST            "66879EE7-45AE-4704-8E03-19F998EFDE73"
 #define LXa_PROFILE1DPREDEST            "profile1DPresetDestination2" 
 #define LXu_PROFILE2DPREDEST            "449009ED-847D-4925-94BC-C5E8ECCAD515"
 #define LXa_PROFILE2DPREDEST            "profile2DPresetDestination2"

ILxProfile1DPreDest Definition

1D profile is a single path consist of lines and cubic bezier curves and it would be used for a parametric function to modulate a scale parameter along a path in modeling tools such as tube, sketch extrude and path step generator. The 1D profile would be also worked with lathe tool as a source profile curve.

The following are methods to build an open path. "MoveTo" sets the start position. "LineTo" makes a segment line with the last position and the given position. "CurveTo" defines a cubic bezier curve.

(27) SDK: Profile1DPreDest::MoveTo
         LXxMETHOD( LxResult,
 MoveTo) (
         LXtObjectID              self,
         double                   x,
         double                   y);

(28) SDK: Profile1DPreDest::LineTo
         LXxMETHOD( LxResult,
 LineTo) (
         LXtObjectID              self,
         double                   x,
         double                   y);

(29) SDK: Profile1DPreDest::CurveTo
         LXxMETHOD( LxResult,
 CurveTo) (
         LXtObjectID              self,
         double                   x0,
         double                   y0,
         double                   x1,
         double                   y1,
         double                   x2,
         double                   y2);

"Evaluate" method returns X or Y value at position 't' along the path. If 'NORMALIZE' is set, it returns the normalized value between 0 and 1. If 'RESETZERO' is set, the origin is reset to the minimum of the bbox.

(30) SDK: Profile1DPreDest::Evaluate
         LXxMETHOD( double,
 Evaluate) (
         LXtObjectID              self,
         double                   t,
         int                      flags,
         int                      axis);

(31) SDK: LXPROFILEf_NORMALIZE, etc. defines

"PathSteps" generates all freezed positions and it returns the number of steps. "tol" is allowable maximum height when the function subdivides bezier curve to polyline. If "nstep" is zero, it returns only returns the best number of steps with the given tolerance.

(32) SDK: Profile1DPreDest::PathSteps
         LXxMETHOD( int,
 PathSteps) (
         LXtObjectID              self,
         double                   tol,
         int                      flags,
         double                  *x,
         double                  *y,
         int                      nstep);

"Box" method sets the bounding box on the profile space.

(33) SDK: Profile1DPreDest::Box
         LXxMETHOD( LxResult,
 Box) (
         LXtObjectID              self,
         LXtBBox                 *box);

"Count" method returns the number of profile in the packet.

(34) SDK: Profile1DPreDest::Count
         LXxMETHOD( unsigned,
 Count) (
         LXtObjectID              self);

"SelectByIndex" method sets the current profile to generate by "PathSteps" by index. The index must be between 0 to count-1.

(35) SDK: Profile1DPreDest::SelectByIndex
         LXxMETHOD( LxResult,
 SelectByIndex) (
         LXtObjectID              self,
         unsigned                 index);

"SelectByParameter" method sets the current profile to generate by "PathSteps" by parameter value between 0.0 to 1.0."PathSteps" generates an interpolated x and y positions at 't'.

(36) SDK: Profile1DPreDest::SelectByParameter
         LXxMETHOD( LxResult,
 SelectByParameter) (
         LXtObjectID              self,
         double                   t);

"SelectByVertex" method sets the current profile to generate by "PathSteps" for the given vertex.

(37) SDK: Profile1DPreDest::SelectByVertex
         LXxMETHOD( LxResult,
 SelectByVertex) (
         LXtObjectID              self,
         LXtMeshID                meshID,
         LXtPointID               pointID);

(38) SDK: empty Profile1DPreDest User Class

Empty Profile1DPreDest Python user class.

(39) PY: empty Profile1DPreDest user class
 pass

ILxProfile1DPreDest1 (Legacy Interface)

This interface was retired in modo 10.1, and was replaced with an updated one that adds a method for multiple profile support.

(40) SDK: LXu_PROFILE1DPREDEST1, etc. defines
 #define LXu_PROFILE1DPREDEST1           "A4E5FAD3-E3A7-4ed9-A1E3-4EB0D31A4187"
 #define LXa_PROFILE1DPREDEST1           "profile1DPresetDestination"

(41) SDK: Profile1DPreDest1::MoveTo, etc.
         LXxMETHOD( LxResult,
 MoveTo) (
         LXtObjectID              self,
         double                   x,
         double                   y);
 
         LXxMETHOD( LxResult,
 LineTo) (
         LXtObjectID              self,
         double                   x,
         double                   y);
 
         LXxMETHOD( LxResult,
 CurveTo) (
         LXtObjectID              self,
         double                   x0,
         double                   y0,
         double                   x1,
         double                   y1,
         double                   x2,
         double                   y2);
 
         LXxMETHOD( double,
 Evaluate) (
         LXtObjectID              self,
         double                   t,
         int                      flags,
         int                      axis);
 
         LXxMETHOD( int,
 PathSteps) (
         LXtObjectID              self,
         double                   tol,
         int                      flags,
         double                  *x,
         double                  *y,
         int                      nstep);
 
         LXxMETHOD( LxResult,
 Box) (
         LXtObjectID              self,
         LXtBBox                 *box);

ILxColorPreDest

The color preset destination is used to apply color presets to a target. Due to the various ways that colors can be used, we let the destination decide how to actually perform the apply.

The destination works by the preset loader calling its various methods to set up state, followed by the Apply() method. Appy() should execute a command (thus ensuring it is undoable) that actually applies the contents of the object to the desired target.

(42) SDK: LXu_COLORPREDEST, etc. defines
 #define LXu_COLORPREDEST                "307b5aab-f8df-4c5b-b916-223172ea921e"
 #define LXa_COLORPREDEST                "colorPresetDestination"

This method is called by the preset server to set the HDR RGB color on the destination. If this method fails, Apply() will not be called.

Colors should always be set in linear space.

(43) SDK: ColorPreDest::SetColor
         LXxMETHOD( LxResult,
 SetColor) (
         LXtObjectID              self,
         const LXtVector          rgb);

This optional method sets the name of the color model server that the color was originally saved in, as well as the color in the model's space. Only color pickers generally care about this.

(44) SDK: ColorPreDest::SetColorModel
         LXxMETHOD( LxResult,
 SetColorModel) (
         LXtObjectID              self,
         const char              *name,
         const double            *vec);

SetColor() will always be called, but SetColorModel() may not be. Once set, the preset loader will call Apply() so that the destination can perform its specific apply of the color to the target, preferably through a command (to ensure that it is undable and scriptable).

(45) SDK: ColorPreDest::Apply
         LXxMETHOD( LxResult,
 Apply) (
         LXtObjectID              self);

(46) SDK: empty ColorPreDest User Class

Empty ColorPreDest Python user class.

(47) PY: empty ColorPreDest user class
 pass

BrushTool Presets

Brush Tool presets have no destination object, because they apply their embedded ToolPreset directly to the global toolpipe using the tpipe.qq API. Nevertheless, these guys need their own unique GUIDs, since they could also be recognized for the images they are (they are PNG files with a toolpreset config snippet in comment metadata) which can lead to confusion.

(48) SDK: LXu_BRUSHTOOLPRESET, etc. defines
 #define LXu_BRUSHTOOLPRESET             "D03E22CE-970E-4CC1-BF76-A74639624647"
 #define LXa_BRUSHTOOLPRESET             "brushToolPreset"