preview (lx_preview.hpp)

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


Preview SDK (ILxPreviewService and ILxPreview)

The Preview SDK API allows a plug-in to create and perform headless, interactive Preview renders.

The Preview service is solely for the purpose of creating a preview object.

(1) SDK: Declarations
 #define LXu_PREVIEWSERVICE       "0491f901-6eee-48e4-a4d0-b2e6d10624b6"
 #define LXa_PREVIEWSERVICE       "previewservice"

(2) SDK: ILxPreviewService interface
         LXxMETHOD (   LxResult,
 CreatePreview) (
         LXtObjectID               self,
         void                    **ppvObj);

(3) SDK: ILxPreviewService interface
         LXxMETHOD (     LxResult,
 GetMeshPreview) (
         LXtObjectID               self,
         LXtObjectID               item,
         int                       width,
         int                       height,
         void                    **ppvObj);

(4) User Service Class: PreviewService method
         bool
 NewPreview (
         CLxLoc_Preview           &preview )
 {
         LXtObjectID               obj;
 
         if (LXx_FAIL (CreatePreview (&obj)))
                 return false;
 
         return preview.take (obj);
 }

Empty preview service Python user class.

(5) PY: PreviewService method
 pass

The Preview object is where all the interesting things happen.

(6) SDK: Declarations
 #define LXu_PREVIEW             "6817942a-375d-485f-b927-af93d1391d73"
 #define LXa_PREVIEW             "preview"

The first method will start a Preview rendering. The Preview could either be stopped or paused. If it's neither, this will have no effect.

(7) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 Start) (
         LXtObjectID               self);

And this method will stop it.

(8) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 Stop) (
         LXtObjectID               self);

Alternatively, we can pause the Preview. This stops rendering, but a future start will not clear the image and will resume where it left off, unless the scene has been updated.

(9) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 Pause) (
         LXtObjectID               self);

This function will both set Preview such that the next time it starts, it will do a full update, completely rebuilding all the render data and tableau from scratch.

(10) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 Reset) (
         LXtObjectID               self);

This method is used to set the resolution of a Preview render. If Preview is currently rendering, it will stop and restart Preview once it has updated the resolution.

(11) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 SetRes) (
         LXtObjectID               self,
         int                       width,
         int                       height);

Sets what time to render at. Currently this calls select.time but might change in future to render at a different time

(12) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 SetRenderTime) (
         LXtObjectID               self,
         double                    time );

This method is used to set the quality of a Preview render.

(13) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 SetQuality) (
         LXtObjectID               self,
         int                       quality,
         int                       samples);

Sets whether to render motion blur or not

(14) SDK: ILxPreview interface
         LXxMETHOD ( LxResult,
 SetMotionBlur) (
         LXtObjectID               self,
         int                       enable);

Sets whether to render all outputs or just do a final color output

(15) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 SetRenderAllOutputs) (
         LXtObjectID               self,
         int                       enable);

Sets whether to use all threads or not.

(16) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 SetUseAllThreads) (
         LXtObjectID               self,
         int                       enable);

Set whether the Preview should render in stereo or not.

(17) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 SetStereo) (
         LXtObjectID               self,
         int                       enable,
         int                       eye);

This function takes a ILxPreviewNotifier object, which will get notified when a new image is available.

(18) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 SetNotifier) (
         LXtObjectID             self,
         LXtObjectID             notifier);

Sets if Preview should set the alpha channel

(19) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 SetAlpha) (
         LXtObjectID             self,
         int                     enable );

Is used to enable/disable per preview camera overrides. If enabled, preview specific camera attributes will be used in place of attributes specific by a camera item in the scene. If disabled then the camera attributes are got from a camera item. Camera overrides allow us to change the camera settings without changing the scene itself. The settings are per preview and so do not affect any other views of the Cinema.

The SetCameraOverride set of preview methods are used for setting these preview specific fields.

(20) SDK: ILxPreview interface
   LXxMETHOD (   LxResult,
 UseCameraOverride) (
         LXtObjectID             self,
         int                     useCameraOverride);

Sets the camera matrix. This will only be used when 'UseCameraOverride' is enabled.

(21) SDK: ILxPreview interface
   LXxMETHOD (   LxResult,
 SetCameraOverrideTransform) (
         LXtObjectID             self,
         const LXtMatrix4 transform);

Sets the field of view for a camera that is tied only to the preview. Setting this will not change the state of any camera items.

(22) SDK: ILxPreview interface
   LXxMETHOD (   LxResult,
 SetCameraOverrideFocalLength) (
         LXtObjectID     self,
         float           focalLength);

Sets the horizontal aperture for a camera that is tied only to the preview. Setting this will not change the state of any camera items.

(23) SDK: ILxPreview interface
   LXxMETHOD (   LxResult,
 SetCameraOverrideApertureX) (
         LXtObjectID     self,
         float           apertureX);

Sets the vertical aperture for a camera that is tied only to the preview. Setting this will not change the state of any camera items.

(24) SDK: ILxPreview interface
   LXxMETHOD (   LxResult,
 SetCameraOverrideApertureY) (
         LXtObjectID     self,
         float           apertureY);

Sets the projection type of a camera that is tied only to the preview. Setting this will not change the state of any camera items. The projection type can be set to one of the following integers:

PERSP 0 ORTHO 1 CYLINDRICAL 2 SPHERICAL 3

(25) SDK: ILxPreview interface
   LXxMETHOD (   LxResult,
 SetCameraOverrideProjectionType) (
         LXtObjectID     self,
         int             projectionType);

Get the current resolution width of a Preview render.

(26) SDK: ILxPreview interface
         LXxMETHOD (     int,
 GetResWidth) (
         LXtObjectID               self );

Get the current resolution height of a Preview render.

(27) SDK: ILxPreview interface
         LXxMETHOD (     int,
 GetResHeight) (
         LXtObjectID               self );

Returns what frame preview is currently being rendered.

(28) SDK: ILxPreview interface
         LXxMETHOD (     double,
 GetCurrentTime) (
         LXtObjectID               self );

Query whether the render is complete. It returns LXe_TRUE or LXe_FALSE;

(29) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 IsComplete) (
         LXtObjectID               self);

And finally, we can get the current state of the rendering image. The client must release this object once it's done.

(30) SDK: ILxPreview interface
         LXxMETHOD (     LxResult,
 GetBuffer) (
         LXtObjectID               self,
         void                    **ppvObj);

It also takes in the number of average AA samples to be fired per pixel. If the value is zero or negative, it will use the default values. Typically this is something like MAX (64, renderSettings) for draft mode, renderSettings for final mode, and some really high number (currently 16384) for extended mode.

(31) SDK: Declarations

This is the PreviewNotifier interface class that users can implement to get notified when a preview image is availble.

(32) SDK: Declarations
 #define LXu_PREVIEWNOTIFIER             "352039c2-8b70-46db-9a83-1e05fd887fc0"
 #define LXa_PREVIEWNOTIFIER             "previewnotifier"

(33) SDK: ILxPreviewNotifier interface
         LXxMETHOD (     LxResult,
 Notify) (
         LXtObjectID                      self,
         const LXtRenderOutputProcess    *rndrProcess,
         LXtObjectID                      image,
         int                              completed );

(34) User Service Class: Preview method
         bool
 GetImage (
         CLxLoc_Image             &image )
 {
         LXtObjectID               obj;
 
         if (LXx_FAIL (GetBuffer (&obj)))
                 return false;
 
         return image.take (obj);
 }

Empty Preview Python user class.

(35) PY: Preview method
 pass

(36) PY: PreviewNotifier method
 pass