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: Declarations
 #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: ILxShaderPreDest interface
         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: ILxShaderPreDest interface
         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: ILxShaderPreDest interface
         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: ILxShaderPreDest interface
         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: ILxShaderPreDest interface
         LXxMETHOD( LxResult,
 GetTag) (
         LXtObjectID              self,
         LXtID4                   type,
         const char             **tag);

This method returns the preset mode either add or apply.

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

(8) User Class: ShaderPreDest method

Empty ShaderPreDest Python user class.

(9) PY: ShaderPreDest method
 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: Declarations
 #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: ILxMeshLayerPreDest interface
         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: ILxMeshLayerPreDest interface
         LXxMETHOD( LxResult,
 Transform) (
         LXtObjectID              self,
         LXtMatrix4               xform);

(13) SDK: Declarations

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

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

(15) User Class: MeshLayerPreDest method

Empty MeshLayerPreDest Python user class.

(16) PY: MeshLayerPreDest method
 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: Declarations
 #define LXu_SCENEITEMPREDEST            "F81AD9DB-6068-4782-B1BB-7F45233682DC"
 #define LXa_SCENEITEMPREDEST            "sceneItemPresetDestination"

ILxSceneItemPreDest Definition

Return the ILxScene

(18) SDK: ILxSceneItemPreDest interface
         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: ILxSceneItemPreDest interface
         LXxMETHOD( LxResult,
 Item) (
         LXtObjectID               self,
         int                      *mode,
         void                    **ppvObj);

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

(20) SDK: ILxSceneItemPreDest interface
         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: ILxSceneItemPreDest interface
         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: ILxSceneItemPreDest interface
         LXxMETHOD( LxResult,
 Orientation) (
         LXtObjectID               self,
         LXtMatrix                 xfrm);

(23) User Class: SceneItemPreDest method

Empty SceneItemPreDest Python user class.

(24) PY: SceneItemPreDest method
 pass

Photometry Presets

(25) SDK: Declarations
 #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: Declarations
 #define LXu_PROFILE1DPREDEST            "A4E5FAD3-E3A7-4ed9-A1E3-4EB0D31A4187"
 #define LXa_PROFILE1DPREDEST            "profile1DPresetDestination" 
 #define LXu_PROFILE2DPREDEST            "F845F4AD-7DFC-4a41-98D1-0FFB2CA744FB"
 #define LXa_PROFILE2DPREDEST            "profile2DPresetDestination"

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: ILxProfile1DPreDest interface
         LXxMETHOD( LxResult,
 MoveTo) (
         LXtObjectID              self,
         double                   x,
         double                   y);

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

(29) SDK: ILxProfile1DPreDest interface
         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: ILxProfile1DPreDest interface
         LXxMETHOD( double,
 Evaluate) (
         LXtObjectID              self,
         double                   t,
         int                      flags,
         int                      axis);

(31) SDK: Declarations

"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: ILxProfile1DPreDest interface
         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: ILxProfile1DPreDest interface
         LXxMETHOD( LxResult,
 Box) (
         LXtObjectID              self,
         LXtBBox                 *box);

(34) User Class: Profile1DPreDest method

Empty Profile1DPreDest Python user class.

(35) PY: Profile1DPreDest method
 pass

ILxProfile2DPreDest Definition

2D profile is a 2-dimentional pattern shape consist of lines and cubic bezier curves. This profile would be useful when it is used with sweep tools.

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.

(36) SDK: ILxProfile2DPreDest interface
         LXxMETHOD( LxResult,
 MoveTo) (
         LXtObjectID              self,
         double                   x,
         double                   y);

(37) SDK: ILxProfile2DPreDest interface
         LXxMETHOD( LxResult,
 LineTo) (
         LXtObjectID              self,
         double                   x,
         double                   y);

(38) SDK: ILxProfile2DPreDest interface
         LXxMETHOD( LxResult,
 CurveTo) (
         LXtObjectID              self,
         double                   x0,
         double                   y0,
         double                   x1,
         double                   y1,
         double                   x2,
         double                   y2);

"NewPath" starts a new profile in the object. 2D profile allows to have multiple pathes.

(39) SDK: ILxProfile2DPreDest interface
         LXxMETHOD( LxResult,
 NewPath) (
         LXtObjectID              self);

Set closed flag to the current path. The default is true.

(40) SDK: ILxProfile2DPreDest interface
         LXxMETHOD( LxResult,
 Closed) (
         LXtObjectID              self,
         int                      closed);

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

(41) SDK: ILxProfile2DPreDest interface
         LXxMETHOD( LxResult,
 Box) (
         LXtObjectID              self,
         LXtBBox                 *box);

(42) User Class: Profile2DPreDest method

Empty Profile2DPreDest Python user class.

(43) PY: Profile2DPreDest method
 pass

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.

(44) SDK: Declarations
 #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.

(45) SDK: ILxColorPreDest interface
         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.

(46) SDK: ILxColorPreDest interface
         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).

(47) SDK: ILxColorPreDest interface
         LXxMETHOD( LxResult,
 Apply) (
         LXtObjectID              self);

(48) User Class: ColorPreDest method

Empty ColorPreDest Python user class.

(49) PY: ColorPreDest method
 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.

(50) SDK: Declarations
 #define LXu_BRUSHTOOLPRESET             "D03E22CE-970E-4CC1-BF76-A74639624647"
 #define LXa_BRUSHTOOLPRESET             "brushToolPreset"