vp (lx_vp.hpp)

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


2D/3D Viewport API

This module implements global service and scripting APIs for the UV and 3D graphical viewports.

ILxView3D Object

The application 3D and UV viewports are exposed as a list of ILxView3D objects. Clients will generally find a view in the list, then use the ILxView3D interface to get its specific properties.

(1) SDK: Declarations
 #define LXu_VIEW3D              "02DBFE75-C1AB-4E23-A4C9-90508C7CD7C3"
 #define LXa_VIEW3D              "viewport3d"

ILxView3D Geometric Properties

LXtID4 Space (self)
Returns the viewspace type of the view. It will be one of the following for valid indices:

(2) SDK: Declarations
 #define LXi_VPSPACE_MODEL               LXxID4('M','O','3','D')
 #define LXi_VPSPACE_TEXTURE             LXxID4('U','V','2','D')
 #define LXi_VPSPACE_WORLD               LXxID4('W','O','3','D')
 #define LXi_VPSPACE_PREVIEW             LXxID4('P','R','E','V')
 #define LXi_VPSPACE_MODEL2D             LXxID4('M','O','2','D')
 #define LXi_VPSPACE_GRAPH               LXxID4('V','P','G','E')
 #define LXi_VPSPACE_SCHEMATIC           LXxID4('S','C','H','M')

int Axis (self, cam, axis)
Returns the view axis. Note that perspective views return -1, and that UV views always return a Z axis. For convenience, the view's camera mode is also provided. If it or the 'axis' vector pointers are NULL they will not be filled.

(3) SDK: Declarations
 #define LXi_VP_AXIS_X            0
 #define LXi_VP_AXIS_Y            1
 #define LXi_VP_AXIS_Z            2
 #define LXi_VP_AXIS_PERSP       -1
 #define LXi_VP_AXIS_UV           LXi_VP_AXIS_Z
 
 #define LXi_VP_CAM_LEFT         0
 #define LXi_VP_CAM_RIGHT        1
 #define LXi_VP_CAM_TOP          2
 #define LXi_VP_CAM_BOTTOM       3
 #define LXi_VP_CAM_FRONT        4
 #define LXi_VP_CAM_BACK         5
 #define LXi_VP_CAM_PERSP        6

LxResult Bounds (self, x, y, w, h)
Returns the upper left corner coordinates for the view, and its width and height in pixels.

(4) SDK: ILxView3D interface
         LXxMETHOD(  LXtID4,
 Space) (
         LXtObjectID              self);
 
 
         LXxMETHOD(  int,
 Axis) (
         LXtObjectID              self,
         int                     *cam,
         LXtVector                axis);
 
         LXxMETHOD(  LxResult,
 Bounds) (
         LXtObjectID              self,
         int                     *x,
         int                     *y,
         int                     *w,
         int                     *h);

The grab-bag of view styles is exposed with a deceptively simple function that, in turn, depends on a vast and ragged matrix of options and their potential values.

int Style (self, option)
Returns the state of the specified option for the specified view. The option must be one of the LXi_VPSTYLE_* values, and the return state will be the appropriate LXI_VPOPT_* value. For simple2-state options, LXi_VPOPT_OFF and LXi_VPOPT_ON will be returned.

(5) SDK: Declarations
 enum {
         LXi_VPSTYLE_SHADE,
         LXi_VPSTYLE_WIRE,
         LXi_VPSTYLE_VCOLOR,
         LXi_VPSTYLE_SMOOTH,
         LXi_VPSTYLE_BACK,
         LXi_VPSTYLE_VERTS,
         LXi_VPSTYLE_CAGES,
         LXi_VPSTYLE_GUIDES,
         LXi_VPSTYLE_GRID,
         LXi_VPSTYLE_WPLANE,
         LXi_VPSTYLE_IMAGE,
         LXi_VPSTYLE_SELECT,
         LXi_VPSTYLE_SELNORM,
         LXi_VPSTYLE_SELFILL,
         LXi_VPSTYLE_SELBORD,
         LXi_VPSTYLE_SELROLL,
         LXi_VPSTYLE_OVERLAY,
         LXi_VPSTYLE_NULL,
 };
 
         #define LXi_VPOPT_OFF                   0
         #define LXi_VPOPT_ON                    1
 
         #define LXi_VPOPT_SHADE_WIRE            0
         #define LXi_VPOPT_SHADE_SKCH            1
         #define LXi_VPOPT_SHADE_VCLR            2
         #define LXi_VPOPT_SHADE_SHAD            3
         #define LXi_VPOPT_SHADE_TEXT            4
         #define LXi_VPOPT_SHADE_REFL            5
         #define LXi_VPOPT_SHADE_PRG1            6
         #define LXi_VPOPT_SHADE_PRG2            7
 
         #define LXi_VPOPT_WIRE_NONE             0
         #define LXi_VPOPT_WIRE_COLR             1
         #define LXi_VPOPT_WIRE_UNIF             2
 
         #define LXi_VPOPT_VCLR_SEL              0
         #define LXi_VPOPT_VCLR_WGT              1
         #define LXi_VPOPT_VCLR_RGB              2
 
         #define LXi_VPOPT_BACK_WIRE             0
         #define LXi_VPOPT_BACK_FLAT             1
         #define LXi_VPOPT_BACK_ACTV             2

(6) SDK: ILxView3D interface
         LXxMETHOD(  int,
 Style) (
         LXtObjectID              self,
         int                      option);

double PixelSize(self)
Returns the approximate size of a single pixel in model space units.
LxResult Center(self, center)
Returns the position vector for the center of the view.
double EyeVector(self, pos, dir)
Computes the gaze direction and distance for a point at 'pos' in the view. The 'dir' vector is normalized, and the distance from eye to pos is returned by the function.
LxResult Matrix(self, matrix, inverse)
Returns the view transform matrix or its inverse.
LxResult Angles(self, hpb)
Returns the view transformation of the specified view as heading, pitch and bank angles.
int WorkPlane(self, center)
Returns the workplane center and axis
LxResult To3D(self, x, y, pos, axis, flags)
Returns position and nearest axis for the screen coordinates x,y. The flag velues determine whether the position is snapped to the user grid, and whether the workplane is used or not.
LxResult To3DHit(self, x, y, pos, nrm)
Sets the position and normal for the ray hit for screen coordinate x,y. Return LXe_OK if there is a hit, LXe_NOTFOUND if there is no hit.

(7) SDK: Declarations
 #define LXi_VPTO3D_SNAP         1
 #define LXi_VPTO3D_WORK         2

(8) SDK: ILxView3D interface
         LXxMETHOD(  double,
 PixelSize) (
         LXtObjectID              self);
 
         LXxMETHOD(  LxResult,
 Center) (
         LXtObjectID              self,
         LXtVector                center);
 
         LXxMETHOD(  double,
 EyeVector) (
         LXtObjectID              self,
         LXtVector                pos,
         LXtVector                dir);
 
         LXxMETHOD(  LxResult,
 Matrix) (
         LXtObjectID              self,
         LXtMatrix                mat,
         int                      inverse);
 
         LXxMETHOD(  LxResult,
 Angles) (
         LXtObjectID              self,
         LXtVector                hpb);
 
         LXxMETHOD(  int,
 WorkPlane) (
         LXtObjectID              self,
         LXtVector                center);
 
         LXxMETHOD(  LxResult,
 To3D) (
         LXtObjectID              self,
         float                    x,
         float                    y,
         LXtVector                pos,
         int                      flags);
 
         LXxMETHOD(  LxResult,
 To3DHit) (
         LXtObjectID              self,
         float                    x,
         float                    y,
         LXtVector                pos,
         LXtVector                nrm);

ILxView3D Backdrop Properties

Background images in viewports a whole kettle of worms, enjoy.

LxResult Backdrop(self, item)
Returns the ILxItem for the image used by the specified view. Naturally, this object must be released by the client when it is no longer needed. If there is no image, LXe_NOTFOUND will be returned.
const char *BackdropName(self)
Returns the name of the image used by the specified view. If there is no image it will be null.
LxResult BackdropPlace(self, x, y, w, h)
Returns the center position and dimensions of the backdrop image. If there is no image, LXe_NOTFOUND will be returned.
int BackdropAspect(self, asp)
Returns the aspect ratio of the backdrop image, and whether the aspect is locked. If there is no image, LXe_NOTFOUND will be returned.
int BackdropOrient(self, ang)
Returns the rotation and horizontal-flip state of the backdrop image. If there is no image, LXe_NOTFOUND will be returned.
int BackdropLook(self, brit, cont, trans)
Returns the invert state and fills brightness, contrast, and transparency of the backdrop image. If there is no image, LXe_NOTFOUND will be returned.
int BackdropRender(self, res, blend)
Returns the overlay state and fills resolution and pixel-blending of the backdrop image. If there is no image, LXe_NOTFOUND will be returned.

(9) SDK: ILxView3D interface
         LXxMETHOD(  LxResult,
 Backdrop) (
         LXtObjectID              self,
         void                   **item);
 
         LXxMETHOD(  const char*,
 BackdropName) (
         LXtObjectID              self);
 
         LXxMETHOD(  LxResult,
 BackdropPlace) (
         LXtObjectID              self,
         double                  *cx,
         double                  *cy,
         double                  *w,
         double                  *h);
 
         LXxMETHOD(  int,
 BackdropAspect) (
         LXtObjectID              self,
         double                  *asp);
 
         LXxMETHOD(  int,
 BackdropOrient) (
         LXtObjectID              self,
         double                  *ang);
 
         LXxMETHOD(  int,
 BackdropLook) (
         LXtObjectID              self,
         double                  *brit,
         double                  *cont,
         double                  *trns);
 
         LXxMETHOD(  int,
 BackdropRender) (
         LXtObjectID              self,
         int                     *resolution,
         int                     *blend);

ILxView3D Raycasting Properties

Raycasting to hit scene elements is facilitated at the viewport level and generalized to use any 2D position on the view. Often the view and the position will be taken from the mouse position.

int HitElement(self, type, x, y, list)
Returns the number of elements of the requested type along the eye vector going through (x,y). The elements themselves are in the read-only array of pointers returned in list. Type should be one of the following

(10) SDK: Declarations
 #define LXi_VPHIT_VERT          LXxID4('V','E','R','T')
 #define LXi_VPHIT_EDGE          LXxID4('E','D','G','E')
 #define LXi_VPHIT_POLY          LXxID4('P','O','L','Y')
 #define LXi_VPHIT_ITEM          LXxID4('I','T','E','M')

(11) SDK: ILxView3D interface
         LXxMETHOD(  int,
 HitElement) (
         LXtObjectID              self,
         LXtID4                   type,
         float                    x,
         float                    y,
         void                   **list);

ILxView3D More Properties

double GridSize (self)
Returns the current grid size of the view.
int FrameRate(self)
Returns the frame rate of the view, meanng how quickly GL is drawing. This is identical to the results displayed in the viewport from the "glmeter" command.

(12) SDK: ILxView3D interface
         LXxMETHOD(  double,
 GridSize) (
         LXtObjectID              self);
 
         LXxMETHOD(  double,
 FrameRate) (
         LXtObjectID              self);
 
         LXxMETHOD(  LxResult,
 SetMatrix) (
         LXtObjectID             self,
         const LXtMatrix         mat);
 
         LXxMETHOD(  LxResult,
 SetCenter) (
         LXtObjectID             self,
         const LXtVector         vec);
 
         LXxMETHOD(  LxResult,
 SetScale) (
         LXtObjectID             self,
         double                  scl);

Empty View3D Python user class.

(13) PY: View3D method
 pass

(14) User Class: View3D method

2D/3D Viewport Global Service

(15) SDK: Declarations
 #define LXu_VIEW3DPORTSERVICE   "D84FF812-E4E9-41DC-B82F-B550ACF2E40A"
 #define LXa_VIEW3DPORTSERVICE   "view3dservice"

ILxView3DportService Object

As with all globals, the first method gets the ILxScriptQueryID interface for the system.

ScriptQuery(self, sq)

(16) SDK: ILxView3DportService interface
         LXxMETHOD(  LxResult,
 ScriptQuery) (
         LXtObjectID              self,
         void                   **ppvObj);

The viewport service will provide access to a list of 3d and UV viewports referenced by index.

int Count(self)
Returns the number of viewports
int Current(self)
Returns the most recently selected viewport's index
LxResult View(self, index, view)
Returns an ILxView3D for viewport at index. Naturally the client is responsible for releasing the returned object.
int Mouse(self, x, y)
Returns the index of the viewport currently under the mouse, or -1 if the mouse is not over a 3D view. The position relative to that view is fillde into x and y, if they are not NULL.
LxResult SetHitUVMap(self, name)
Sets the UV vertex map used for hit testing by tools. If the name is NULL, then the hit vmap is cleared.

(17) SDK: ILxView3DportService interface
         LXxMETHOD(  int,
 Count) (
         LXtObjectID              self);
 
         LXxMETHOD(  int,
 Current) (
         LXtObjectID              self);
 
         LXxMETHOD(  LxResult,
 View) (
         LXtObjectID              self,
         int                      index,
         void                   **ppvObj);
 
         LXxMETHOD(  int,
 Mouse) (
         LXtObjectID              self,
         int                     *x,
         int                     *y);
 
         LXxMETHOD(  LxResult,
 SetHitUVMap) (
         LXtObjectID              self,
         const char              *name);

Empty view3Dport service user classes.

(18) User Service Class: View3DportService method

(19) PY: View3DportService method
 pass

2D/3D Viewport Script API

The viewport scripting interface tries to be self-describing, by providing queries which enumerate the possible queries, as well as queries which enumerate selectors. A query has a form which can be generally expressed as:

query <service> <attribute>[.<sub-attr>] ? <selector>

Where <service> is always 'viewservice' as far as we're concerned, <attribute> is the main object of the query (e.g. 'view'), the optional <sub-attr> picks what aspect of the object we are interested in (e.g. 'center'), and <selector> specifies which of the objects of this type to query. The selector will often be a numeric index into a list, but it may also be a relative specification, like 'next' or 'current'.

One can get a list of valid selectors for some object by appending 's' to <attribute> (e.g. "query viewservice views ?", which will return a list of valid views). Another standard query for objects is <attribute>.N, which gets the number of objects. Finally the set of possible queries for an object with subqueries is is returned by the plain <attribute> query (e.g. "query viewservice view ?").

View Query

These are the possible queries for the 'view' object. The selector query for that query is in brackets:

view [ ]
List of view.* queries
view_types [ ]
List of selectors for queries which use this kind of selector: ('all','Texture','Model', 'Scene')
views [ view_types ]
List of view selectors for views of type specified by the view_type selector
view.N [ view_types ]
Number of views of type specified by selector
view.type [ views ]
Type of view (front, back, perspective, top, UV, etc.)
view.rect [ views ]
The position and size of the view, as x,y,w,h
view.axis [ views ]
An axis vector for the view
view.center [ views ]
3D center position for view
view.scale [ views ]
The approx. size in model units of a single pixel in the view
view.angles [ views ]
View orientation as heading, pitch, bank angles
view.shade [ views ]
Shading mode for view (wireframe, sketch, texture, etc.)
view.wire [ views ]
Wireframe overlay enabled for view (1==on, 0==off)
view.vcolor [ views ]
Vertex coloring mode for view
view.smooth [ views ]
Smoothing enabled for view
view.bgmode [ views ]
Background drawing mode for view
view.verts [ views ]
Vertex visibility enabled
view.cage [ views ]
Cage visibility enabled
view.guide [ views ]
Guide visibility enabled
view.image [ views ]
BG Image name
view.gridSize [ views ]
The current grid size

Mouse Query

Tracking user events and mousing through scripting can be tricky, but this should work:

mouse [ ]
List of mouse.* queries
mouse.view [ ]
Index of view mouse is over (-1 for mouse NOT over UV/3D view)
mouse.pixel [ ]
Current pixel position of cursor
mouse.pos [ ]
Current 3D position of cursor, using something akin to default event translation.
mouse.hitPos [ ]
Gives hit position of geometry under the mouse.
mouse.hitNrm [ ]
Gives hit normal of geometry under the mouse.
mouse.rayDir [ ]
Gives the ray direction from the mouse.

Element Query

element [ ]
List of element.* queries
element_types [ ]
Selectors for element query: 'vert', 'poly', 'edge', 'item'
element.over [ element_types ]
List of elements of type indicated by selector which the mouse if over. The elements are presented in a form suitable for layerservice queries (i.e. layer index, element index or indices).

Palette Query

Preset Query

Simulation Listener

This global listener can be used to track the state changes related to interactive simulation.

(20) SDK: Declarations
 #define LXu_SIMULATIONLISTENER  "628A3377-C56B-4801-878C-8BF87A097D29"
 #define LXa_SIMULATIONLISTENER  "simulationlistener"

These methods are called when the simulation mode starts and ends. The start event is passed a ChannelRead object for reading the outputs of the simulation.

(21) SDK: ILxSimulationListener interface
         LXxMETHOD(  LxResult,
 Start) (
         LXtObjectID              self,
         LXtObjectID              channels);
 
         LXxMETHOD(  LxResult,
 End) (
         LXtObjectID              self);

Current time for the simulation is set here.

(22) SDK: ILxSimulationListener interface
         LXxMETHOD(  LxResult,
 Time) (
         LXtObjectID              self,
         double                   time);

Any time the simulation has new results the listener clients are invalidated.

(23) SDK: ILxSimulationListener interface
         LXxMETHOD(  LxResult,
 Invalidate) (
         LXtObjectID              self);

(24) PY: SimulationListener method
 pass

(25) User Class: SimulationListener method