Vp (lx-vp.hpp)

From The Foundry MODO SDK wiki
Revision as of 21:02, 19 February 2018 by LuxSDKBot (Talk | contribs) (Header Documentation)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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: LXu_VIEW3D, etc. defines
 #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: LXi_VPSPACE_MODEL, etc. defines
 #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: LXi_VP_AXIS_X, etc. defines
 #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: View3D::Space, etc.
         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 {
         #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: View3D::Style
         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: LXi_VPTO3D_SNAP, etc. defines
 #define LXi_VPTO3D_SNAP         1
 #define LXi_VPTO3D_WORK         2

(8) SDK: View3D::PixelSize, etc.
         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: View3D::Backdrop, etc.
         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: LXi_VPHIT_VERT, etc. defines
 #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: View3D::HitElement
         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: View3D::GridSize, etc.
         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);

ILxView3D Viewport Item Properties

These functions are to get item specific properties on the viewport. When "Enable Independent Drawing" is enabled on the viewport, they returns the properties from "Draw Options" on the item.

LxResult ItemShade (self, item, shade) Return the shading style (VPOPT_SHADE_XXX) of the given item.
LxResult ItemColor (self, item, color) Returns the basic wireframe color and alpha of the item.
LxResult ItemSelColor (self, item, color) Returns the wireframe color of the selected item. If the item is not selected, it returs basic wireframe color.
LxResult ItemWireOverlay (self, item, color, wireframe) Returns the wireframe overlay mode and the overlay color of the selected item.
(13) SDK: View3D::ItemShade, etc.
         LXxMETHOD(  LxResult,
 ItemShade) (
         LXtObjectID              self,
         LXtObjectID              item,
         unsigned                *shade);
         LXxMETHOD(  LxResult,
 ItemColor) (
         LXtObjectID              self,
         LXtObjectID              item,
         LXtFVector4              color);
         LXxMETHOD(  LxResult,
 ItemSelColor) (
         LXtObjectID              self,
         LXtObjectID              item,
         LXtFVector4              color);
         LXxMETHOD(  LxResult,
 ItemWireOverlay) (
         LXtObjectID              self,
         LXtObjectID              item,
         LXtFVector4              color,
         unsigned                *wireframe);

ILxView3D Viewport Deformers Status

LxResult Deformers (self) Returns LXe_TRUE if "Deformers" stat of the view is ON, otherwise it returns LXe_FALSE.
(14) SDK: View3D::Deformers
         LXxMETHOD(  LxResult,
 Deformers) (
         LXtObjectID              self);

ILxView3D Viewport Item Visibility

LxResult ItemIsVisible (self, item) Returns LXe_TRUE if the item is visible, otherwise it returns LXe_FALSE.
(15) SDK: View3D::ItemIsVisible
         LXxMETHOD(  LxResult,
 ItemIsVisible) (
         LXtObjectID              self,
         LXtObjectID              item);

ILxView3D UV Hit Testing

LxResult ToUVHit(self, x, y, u, v) Sets the U and V for the ray hit for screen coordinate x,y. Return LXe_OK if there is a hit, LXe_NOTFOUND if there is no hit.
(16) SDK: View3D::ToUVHit
         LXxMETHOD(  LxResult,
 ToUVHit) (
         LXtObjectID              self,
         const char              *name,
         float                    x,
         float                    y,
         unsigned                 layer,
         float                    *u,
         float                    *v);

Item Channels

An item type can define a tag for a deferred update channel. This is an integer channel that will be tested to see if deferred updates should be done. Any non-zero int value enables deferred updates.

 #define LXsPKG_DEFERRED_UPDATE          "pkg.deferredUpdate"

GL Viewport Indirection

The GLViewport object allows clients to get a fully domesticated GL viewport of their own. The object is not associated with any on-screen viewport and can be used with no nexus-native windows at all. Instead it represents GL state that can draw and react to input.

(18) SDK: LXu_GLVIEWPORT define
 #define LXu_GLVIEWPORT          "9F4D9937-FF49-45E4-9781-8085A9463661"

Initialize the new viewport object with the client interface.

(19) SDK: GLViewport::Initialize
         LXxMETHOD(  LxResult,
 Initialize) (
         LXtObjectID              self,
         LXtObjectID              client);

Set the size of the GL area.

(20) SDK: GLViewport::SetSize
         LXxMETHOD(  LxResult,
 SetSize) (
         LXtObjectID              self,
         unsigned                 w,
         unsigned                 h);

Call this to draw the viewport. The GL context must be set correctly.

(21) SDK: GLViewport::Draw
         LXxMETHOD(  LxResult,
 Draw) (
         LXtObjectID              self);

Call this to process a mouse event.

(22) SDK: GLViewport::MouseEvent
         LXxMETHOD(  LxResult,
 MouseEvent) (
         LXtObjectID              self,
         unsigned                 event);

(23) SDK: LXiGLMOUSE_EVENT_NONE, etc. defines

The client object allows the owner of the viewport to provide essential information to the GL viewport, and to handle invalidation.

 #define LXu_GLVIEWPORTCLIENT    "2975C75E-1F2C-4448-98BB-D3FA8ADF8595"

This is called by the GL viewport when it needs to redraw.

(25) SDK: GLViewportClient::Invalidate
         LXxMETHOD(  LxResult,
 Invalidate) (
         LXtObjectID              self);

Return the current mouse position.

(26) SDK: GLViewportClient::MousePosition
         LXxMETHOD(  LxResult,
 MousePosition) (
         LXtObjectID              self,
         int                     *x,
         int                     *y);

Return the current mouse button depressed.

(27) SDK: GLViewportClient::MouseButton
         LXxMETHOD(  LxResult,
 MouseButton) (
         LXtObjectID              self,
         unsigned                *button);

(28) SDK: LXiGLMOUSE_BUTTON_NONE, etc. defines

Return the current pressure for stylus devices.

(29) SDK: GLViewportClient::TabletPressure
         LXxMETHOD(  LxResult,
 TabletPressure) (
         LXtObjectID              self,
         double                  *press);

Return the current tilt for stylus devices.

(30) SDK: GLViewportClient::TabletTilt
         LXxMETHOD(  LxResult,
 TabletTilt) (
         LXtObjectID              self,
         double                  *tilt);

2D/3D Viewport Global Service

(31) SDK: LXu_VIEW3DPORTSERVICE, etc. defines
 #define LXu_VIEW3DPORTSERVICE   "D84FF812-E4E9-41DC-B82F-B550ACF2E40A"
 #define LXa_VIEW3DPORTSERVICE   "view3dservice"

Empty view3Dport service user classes.

(32) SDK: empty View3DportService User Class

(33) PY: empty Service.View3Dport user class

ILxView3DportService Object

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

ScriptQuery(self, sq)
(34) SDK: View3DportService::ScriptQuery
         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.
(35) SDK: View3DportService::Count, etc.
         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);

(36) SDK: View3DportService::InvalidateOverrider
         LXxMETHOD(  int,
 InvalidateOverrider) (
         LXtObjectID              self,
         LXtObjectID              scene,
         const char              *pkgName);

This function allocates a GL material object (ILxGLMaterial) with given bin, item and view objects.

(37) SDK: View3DportService::GLMaterial
         LXxMETHOD(  LxResult,
 GLMaterial) (
         LXtObjectID              self,
         LXtObjectID              bin,
         LXtObjectID              item,
         LXtObjectID              view,
         void                    **ppvObj);

Converts a ILxTriangleGroup into an ILxViewObject.

(38) SDK: View3DportService::TriGroupToViewObject
         LXxMETHOD(  LxResult,
 TriGroupToViewObject) (
         LXtObjectID               self,
         unsigned int              type,
         LXtObjectID               triGroup,
         void                    **ppvObj);

Converts an ILxImage object into a ILxGLImage object for drawing.

(39) SDK: View3DportService::ImageToGLImage
         LXxMETHOD(  LxResult,
 ImageToGLImage) (
         LXtObjectID               self,
         LXtObjectID               image,
         void                    **ppvObj);

Allocate a GLViewport.

(40) SDK: View3DportService::AllocGLViewport
         LXxMETHOD(  LxResult,
 AllocGLViewport) (
         LXtObjectID               self,
         void                    **ppvObj);

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.

(41) SDK: LXu_SIMULATIONLISTENER, etc. defines
 #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.

(42) SDK: SimulationListener::Start, etc.
         LXxMETHOD(  LxResult,
 Start) (
         LXtObjectID              self,
         LXtObjectID              channels);
         LXxMETHOD(  LxResult,
 End) (
         LXtObjectID              self);

Current time for the simulation is set here.

(43) SDK: SimulationListener::Time
         LXxMETHOD(  LxResult,
 Time) (
         LXtObjectID              self,
         double                   time);

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

(44) SDK: SimulationListener::Invalidate
         LXxMETHOD(  LxResult,
 Invalidate) (
         LXtObjectID              self);

(45) PY: empty SimulationListener user class

(46) SDK: empty SimulationListener User Class