raycast (lx_raycast.hpp)

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


Introduction

This module implements raytracing and lighting interfaces that can be used during rendering with sample vectors.

Raytracing Objects

Shaders often need to raycast the scene, this can be done using the Raycast object. There is alot more than just raycasting, there is the extended raytracing flag with all the raytracing flags.

Pixel Geometry

Every pixel can be evaluated for its basic geometry which is stored in this structure:

(1) SDK: LXpPixelGeometry struct
 LXtFVector               nrm;
 LXtFVector               wpos;
 LXtFVector               opos;
 float                    dist;
 void                    *gsrf;

Same as the LXpPixelGeometry, but also supports geometry segments

(2) SDK: LXpPixelGeometrySeg struct
 LXtFVector               nrm;
 LXtFVector               wpos;
 LXtFVector               opos;
 float                    dist;
 void                    *gsrf;
 void                    *gseg;

Raycast Interface

The raycast object is exposed to clients via the raycast interface, which is actually a packet in the sample vector.

RayPush/Pop
Push and pop a new ray on the stack. This is required for recursive raytracing and should wrap all the calls to raycast, raytrace and pixelGeometry.
Raycast
Casts a ray in the scene and returns the hit distance or -1 if nothing was hit.
Raytrace
Raytraces the scene, the results can be extracted from the sample vector.
InternalShade
Will shade the current hit point using modo's internal shader, and settings set through the LXpSampleParms packet.
PixelToRay
Returns the ray direction given the pixel. the 'mode' is either relative or absolute, relative pixels are set from the current pixel position.
PixelGeometry
Returns the pixel geometric information for the given pixel. This is really a wrapper on the raycast function.
Irradiance
Evaluates the irradiance at the given point (and direction) in space.

(3) SDK: ILxRaycast interface
         LXxMETHOD(  ILxUnknownID,
 RayPush) (
         LXtObjectID              self,
         LXtObjectID              vector);
 
         LXxMETHOD(  LxResult,
 RayPop) (
         LXtObjectID              self,
         LXtObjectID              vector);
 
         LXxMETHOD(  float,
 Raycast) (
         LXtObjectID              self,
         LXtObjectID              vector,
         const LXtVector          pos,
         const LXtFVector         dir);
 
         LXxMETHOD(  float,
 Raytrace) (
         LXtObjectID              self,
         LXtObjectID              vector,
         const LXtVector          pos,
         const LXtFVector         dir,
         int                      flags);
 
         LXxMETHOD( LxResult,
 InternalShade) (
         LXtObjectID              self,
         LXtObjectID              vector);
 
         LXxMETHOD(  LxResult,
 GetSurfaceID) (
         LXtObjectID              self,
         LXtObjectID              vector,
         void                     **id);
 
         LXxMETHOD(  int,
 GetSurfaceType) (
         LXtObjectID              self,
         LXtObjectID              vector);
 
         LXxMETHOD(  LxResult,
 PixelToRay) (
         LXtObjectID              self,
         LXtObjectID              vector,
         int                      mode,
         float                    x,
         float                    y,
         LXpSampleRay            *sRay);
 
         LXxMETHOD(  LxResult,
 PixelGeometry) (
         LXtObjectID              self,
         LXtObjectID              vector,
         int                      mode,
         float                    x,
         float                    y,
         LXpPixelGeometry        *pGeo);
 
         LXxMETHOD(  LxResult,
 PixelGeometrySeg) (
         LXtObjectID              self,
         LXtObjectID              vector,
         int                      mode,
         float                    x,
         float                    y,
         LXpPixelGeometrySeg     *pGeo);

Raycast pixel modes.

(4) SDK: Declarations

Raycast flags. These are made of 3 flag types, that describe the full context of the ray:

SCOPE this is what the raytracer sees (polygons, volumetrics, etc)
EVAL this is what the raytracer evaluates when the ray intersects something (material, shading, opacity, etc)
TYPE this is the ray type which specifies the evaluation context (camera rays, indirect rays, etc). The context is important for various
raytracing optimizations and surface visibility options.

(5) SDK: Declarations
 /*
  * Primary rays are for collecting samples for deferred shading, so
  * only the normal needs to be evaluated at the hit point.
  */
 #define LXmRAY_PRIMARY   LXfRAY_SCOPE_POLYGONS | LXfRAY_SCOPE_IMPLICITSURF | LXfRAY_EVAL_NORMAL | LXfRAY_TYPE_CAMERA
 
 /*
  * Preview, reflection, refraction, and indirect rays need to evaluate
  * full shading at the hit point.  For indirect rays, volumetrics are
  * optional.
  */
 #define LXmRAY_PREVIEW   LXfRAY_SCOPE_POLYGONS | LXfRAY_SCOPE_IMPLICITSURF | LXfRAY_SCOPE_VOLUMETRICS | LXfRAY_SCOPE_ENVIRONMENT | LXfRAY_EVAL_SHADING | LXfRAY_TYPE_CAMERA
 
 #define LXmRAY_REFLECT   LXfRAY_SCOPE_POLYGONS | LXfRAY_SCOPE_IMPLICITSURF | LXfRAY_SCOPE_VOLUMETRICS | LXfRAY_SCOPE_ENVIRONMENT |LXfRAY_EVAL_SHADING | LXfRAY_TYPE_REFLECT
 
 #define LXmRAY_REFRACT   LXfRAY_SCOPE_POLYGONS | LXfRAY_SCOPE_IMPLICITSURF | LXfRAY_SCOPE_VOLUMETRICS | LXfRAY_SCOPE_ENVIRONMENT | LXfRAY_SCOPE_BACKFACE | LXfRAY_EVAL_SHADING | LXfRAY_TYPE_REFRACT
 
 #define LXmRAY_INDIRECT  LXfRAY_SCOPE_POLYGONS | LXfRAY_SCOPE_IMPLICITSURF | LXfRAY_SCOPE_ENVIRONMENT | LXfRAY_EVAL_SHADING | LXfRAY_TYPE_INDIRECT
 
 /*
  * Shadow and occlusion rays only need to know the opacity at the hit
  * point.
  */
 #define LXmRAY_SHADOW    LXfRAY_SCOPE_POLYGONS | LXfRAY_SCOPE_IMPLICITSURF  | LXfRAY_SCOPE_VOLUMETRICS | LXfRAY_SCOPE_BACKFACE | LXfRAY_EVAL_OPACITY | LXfRAY_TYPE_SHADOW
 
 #define LXmRAY_OCCLUSION         LXfRAY_SCOPE_POLYGONS | LXfRAY_SCOPE_IMPLICITSURF  | LXfRAY_SCOPE_VOLUMETRICS | LXfRAY_SCOPE_BACKFACE | LXfRAY_EVAL_OPACITY | LXfRAY_TYPE_OCCLUSION
 
 /*
  * Caustic rays (photons) only need to know the material parameters at
  * the hit point.
  */
 #define LXmRAY_CAUSTIC   LXfRAY_SCOPE_POLYGONS | LXfRAY_SCOPE_IMPLICITSURF | LXfRAY_SCOPE_BACKFACE | LXfRAY_EVAL_MATERIAL | LXfRAY_EVAL_SHADING | LXfRAY_TYPE_CAUSTIC
 
 /*
  * Subsurface rays only need to know the irradiance at the hit point.
  */
 #define LXmRAY_SUBSURFACE        LXfRAY_SCOPE_POLYGONS | LXfRAY_SCOPE_IMPLICITSURF | LXfRAY_SCOPE_BACKFACE | LXfRAY_SCOPE_BACKONLY | LXfRAY_EVAL_IRRADIANCE | LXfRAY_TYPE_SUBSURFACE

(6) SDK: Declarations
 #define LXu_RAYCAST             "7E2C439F-3B4D-4C3A-9B4A-18307EF9FC36"
 #define LXa_RAYCAST             "raycast2"
 #define LXsP_RAYCAST            "raycast"

Empty Raycast Python user class.

(7) PY: Raycast method
 pass

Lighting Interface

The lighting object can be used to evaluate the light samples reaching the surface from the various light sources in the scene. It can also be used to evaluate the environment for global illumination. The lighting object is a packet object that can be accessed from the sample vector.

LightSourceCount
Returns the number of light samples hitting the current surface
LightSourceByIndex
Returns the light source given by its index, each light source has informations about the light element it is coming from and the direction to the current sample position.
LightSourceEvaluate
This evaluates the given light source and places the result in 'lum' which accounts for everything including the visibility factor, projected textures and shadows.
EnvironmentEvaluate
This evaluates the environment using the current position and normal packets. The flags are raytrace flags which indicate what the scope of the ray is (environment, surfaces, volumes, etc)
GIRequired
Retursn true if the current surface needs global illumination according to the render settings and the surface properties.

(8) SDK: ILxLighting interface
         LXxMETHOD(  LxResult,
 LightSourceCount) (
         LXtObjectID              self,
         LXtObjectID              vector,
         int                     *num);
 
         LXxMETHOD(  LxResult,
 LightSourceByIndex) (
         LXtObjectID              self,
         LXtObjectID              vector,
         int                      index,
         LXpLightSource          *lSrc);
 
         LXxMETHOD(  LxResult,
 LightSourceEvaluate) (
         LXtObjectID              self,
         LXtObjectID              vector,
         const LXpLightSource    *lSrc,
         LXtFVector               lum);
 
         LXxMETHOD(  LxResult,
 EnvironmentEvaluate) (
         LXtObjectID              self,
         LXtObjectID              vector,
         int                      samples,
         int                      flags,
         LXtFVector               lum);
 
         LXxMETHOD(  int,
 GIRequired) (
         LXtObjectID              self,
         LXtObjectID              vector);

(9) User Class: Lighting method

Empty Lighting Python user class.

(10) PY: Lighting method
 pass

(11) SDK: Declarations
 #define LXu_LIGHTING            "2F6C2A6C-68AF-4E58-B567-A92D5EB732F4"
 #define LXa_LIGHTING            "lighting"
 #define LXsP_LIGHTING           "lighting"

Here is an example of how to get the lighting object from the sample vector. Note that the offset should really be computed outside of the Evaluate function as it is a lookup that is too slow in the context of shader evaluation.

(12) SDK: Lighting object from the sample vector
 CLxLoc_Lighting                  lighting;
 int                              lgt_offset;
 
 lgt_offset  = pkt_service.GetOffset (LXsCATEGORY_SAMPLE, LXsP_LIGHTING);
 pkt_service.PacketObject (vector, lgt_offset, lighting);