RixShadingContext Class Reference

RixShadingContext Class Referenceabstract

#include <RixShading.h>

Inheritance diagram for RixShadingContext:


class  Allocator
struct  Id

Public Types

enum  BuiltinVolume { k_SSDiffusion }
enum  BuiltinBsdf { k_NullBsdf }
enum  BuiltinVar {
  k_P =0, k_PRadius, k_Po, k_Nn,
  k_Ngn, k_Non, k_Tn, k_Vn,
  k_VLen, k_curvature, k_incidentRaySpread, k_incidentRayRadius,
  k_incidentLobeSampled, k_mpSize, k_biasR, k_biasT,
  k_u, k_v, k_w, k_du,
  k_dufp = k_du, k_dv, k_dvfp = k_dv, k_dw,
  k_dwfp = k_dw, k_dPdu, k_dPdv, k_dPdw,
  k_dPdtime, k_time, k_Id, k_outsideIOR,
  k_Oi, k_lpeState, k_launchShadingCtxId, k_motionFore,
  k_motionBack, k_numBuiltinVars
enum  TransformInterpretation { k_AsPoints, k_AsVectors, k_AsNormals }
enum  MemCategory { k_BxdfMem, k_PatternMem }

Public Member Functions

bool HasHits () const
bool HasMisses () const
RixBsdfGetBsdf () const
RixOpacityGetOpacity () const
RixVolumeIntegratorGetVolume () const
virtual bool HasVolume (RixSCVolumeSelector) const =0
virtual RixVolumeIntegratorBeginVolume (RixSCVolumeSelector, RtInt nrays, RtRayGeometry *rays) const =0
virtual void EndVolume (RixVolumeIntegrator *) const =0
RixVolumeIntegratorBeginIncidentVol (RtInt nrays, RtRayGeometry *rays) const
 two convenience methods
RixVolumeIntegratorBeginOppositeVol (RtInt nrays, RtRayGeometry *rays) const
virtual RixShadingContextBeginVolumeSampling () const =0
virtual RixShadingContext const * EndVolumeSampling (RixShadingContext *, RixBXLobeTraits const *exposeVol=NULL, RtInt const *membership=NULL) const =0
virtual std::vector< const
RixShadingContext * > const * 
GetOverlappingVolumes () const =0
virtual RixVolumeIntegratorGetBuiltinVolume (BuiltinVolume, RixBxdfFactory *) const =0
virtual RixBsdfGetBuiltinBsdf (BuiltinBsdf, RixBxdfFactory *) const =0
virtual RixDisplayServices * GetDisplayServices (int version=1) const =0
virtual void GetBuiltinVar (BuiltinVar, RtInt const **var) const =0
virtual void GetBuiltinVar (BuiltinVar, RtFloat const **var) const =0
virtual void GetBuiltinVar (BuiltinVar, RtFloat3 const **var) const =0
virtual void GetBuiltinVar (BuiltinVar, RixLPEState *const **var) const =0
virtual void SetBuiltinVar (BuiltinVar, RtFloat *var)=0
virtual void SetBuiltinVar (BuiltinVar, RtFloat3 *var)=0
virtual RixSCDetail GetPrimVar (char const *name, RixSCType *type, RtInt *arraylen) const =0
virtual RixSCDetail GetPrimVar (char const *name, RtFloat fill, RtFloat const **var, RtFloat const **radius=NULL) const =0
virtual RixSCDetail GetPrimVar (char const *name, RtFloat2 fill, RtFloat2 const **var, RtFloat const **radius=NULL) const =0
virtual RixSCDetail GetPrimVar (char const *name, RtFloat3 fill, RtFloat3 const **var, RtFloat const **radius=NULL) const =0
virtual RixSCDetail GetPrimVar (char const *name, RtConstString **var) const =0
virtual RixSCDetail GetPrimVar (char const *name, RtFloat const **var, RtFloat const **dXdu, RtFloat const **dXdv) const =0
virtual RixSCDetail GetPrimVar (char const *name, RtFloat2 const **var, RtFloat const **dXdu, RtFloat const **dYdu, RtFloat const **dXdv, RtFloat const **dYdv) const =0
virtual RixSCDetail GetPrimVar (char const *name, RtFloat3 const **var, RtFloat const **dXdu, RtFloat const **dYdu, RtFloat const **dZdu, RtFloat const **dXdv, RtFloat const **dYdv, RtFloat const **dZdv) const =0
virtual void SetPrimVar (char const *name, RixSCDetail d, RtFloat *var, RtFloat *radius)=0
virtual void SetPrimVar (char const *name, RixSCDetail d, RtFloat2 *var, RtFloat *radius)=0
virtual void SetPrimVar (char const *name, RixSCDetail d, RtFloat3 *var, RtFloat *radius)=0
virtual void SetPrimVar (char const *name, RixSCDetail d, RtString *var)=0
virtual int Transform (TransformInterpretation interp, char const *fromSpace, char const *toSpace, RtFloat3 *var, RtFloat *radius=NULL) const =0
virtual int GetTransform (char const *fromSpace, char const *toSpace, RtMatrix4x4 const **matrix, int *numMatrices) const =0
virtual RixShadingContextCreateMutableContext () const =0
virtual RixShadingContext const * GetPrimaryContext () const =0
virtual RixShadingContext const * GetContextById (RixShadingContext::Id sctxId) const =0
virtual RixSCDetail EvalParam (RtInt id, RtInt arrayindex, RtInt const **result, RtInt const *dflt=NULL, bool promoteToVarying=false) const =0
virtual RixSCDetail EvalParam (RtInt id, RtInt arrayindex, RtFloat const **result, RtFloat const *dflt=NULL, bool promoteToVarying=false) const =0
virtual RixSCDetail EvalParam (RtInt id, RtInt arrayindex, RtColorRGB const **result, RtColorRGB const *dflt=NULL, bool promoteToVarying=false) const =0
virtual RixSCDetail EvalParam (RtInt id, RtInt arrayindex, RtFloat3 const **result, RtFloat3 const *dflt=NULL, bool promoteToVarying=false) const =0
virtual RixSCDetail EvalParam (RtInt id, RtInt arrayindex, RtMatrix4x4 const **result, RtMatrix4x4 const *dflt=NULL, bool promoteToVarying=false) const =0
virtual RixSCDetail EvalParam (RtInt id, RtInt arrayindex, RtConstString **result, RtConstString *dflt=NULL, bool promoteToVarying=false) const =0
virtual RixSCDetail EvalParam (RtInt id, RtInt arrayindex, RixBxdfFactory **result, RixBxdfFactory *dflt=NULL, bool promoteToVarying=false) const =0
template<class T >
RixSCDetail EvalAndCopyParam (RtInt id, RtInt arrayindex, T **result, T const *dflt=NULL, bool promoteToVarying=false, MemCategory mcat=k_BxdfMem) const
virtual RtInt GetParamId (char const *name, RtInt *paramid) const =0
virtual RtInt GetParamInfo (RtInt paramid, RixSCType *type, RixSCConnectionInfo *cinfo, int *arraylength=NULL) const =0
RtInt GetParamInfo (RtInt paramid, RixSCType *type, bool *isconnected, int *arraylength=NULL) const
virtual void GetNearestHits (RtInt numRays, RtRayGeometry const *rays, RtHitPoint *hits, char const *subset=NULL, RtHitSides hitSides=k_SidesBoth) const =0
virtual void GetLightEmission (RtColorRGB *e) const =0
virtual void * Allocate (size_t n, size_t size, MemCategory m) const =0
template<class T >
T * New (size_t nObjs, MemCategory cat=k_BxdfMem) const

Public Attributes

struct RixShadingContext::Id shadingCtxId
RtInt numPts
struct {
   unsigned   eyePath: 1
   unsigned   lightPath: 1
 true if shading for an eye path
   unsigned   primaryHit: 1
 true if shading for a light path
   unsigned   missContext: 1
 true if shading for a first hit
   unsigned   reyesGrid: 1
 true if this context represents misses
   RixSCShadingMode   shadingMode
   union {
      RixBsdf *   bsdf
      RixOpacity *   opacity
   }   shader
   RixVolumeIntegrator *   volume
RtInt * integratorCtxIndex
RtInt * rayId
RtColorRGB * transmission
RtFloat * pointWeight
void * lightingServicesData
 lightingServicesData is a blind pointer private RixLightingServices data

Detailed Description

RixShadingContext is analogous to a RenderMan grid - it is a group of 1 or more points that may be shaded. The group of points usually arrive through ray traced "hits". In this case, the shading context provides geometric details through its GetPrimVar and GetBuiltinVar methods. Associated with each primvar is a varying filter size that is computed as a function of rendering conditions such as shading rate and ray differentials. The incoming positions are not guaranteed to be neighbors and so do not support requirements for computing first-differences. Rather, differential information is embodied through filter radii and these are only computable for known builtin and primitive variables.

ShadingContexts can also be produced by ray traced "misses". Now only the ray origination information is available and the class of shading activities is limited to cases where no bxdf, builtin and primitive variables are required. RixShadingContexts are comprised exclusively of hits or misses and optionally delivered across the RixIntegratorCtx's GetNearestHits method.

ShadingContexts operate in a small number of modes according to the integration requirements.

Member Enumeration Documentation

BuiltinBsdfs can be constructed cheaply and offer a basic set of capabilities. They differ from Bxdf plugins in that they expose no parameters and thus no BxdfFactories are required.

BuiltinVolumes are "preloaded" and initialized by the renderer. Plugin volumes are usually "compiled-in" to the associated Bxdf. In both cases, the Bxdf's BeginInterior method is invoked to instantiate a VolumeIntegrator object.

Member Function Documentation

virtual void* RixShadingContext::Allocate ( size_t  n,
size_t  size,
MemCategory  m 
) const
pure virtual

Allocate: fast memory allocation support from a memory pool tailored to Pattern and Bxdf plugins. Memory allocated via this interface is managed (freed) by RixShadingContext according to the lifetime requirements of the associated MemCategory. As with many custom memory allocation schemes, clients should use "placement new" and not rely on invocation of a destructor. RixAlloca can be used for intra-procedure dynamic memory allocation.

virtual RixShadingContext* RixShadingContext::BeginVolumeSampling ( ) const
pure virtual

Begin/EndVolumeSampling: can be called by a volume integrator to obtain a mutable shading context for the purposes of sampling its volume region. The resulting shading context has the same size as its creator context. Two options for cleanup are offered. If the volume integrator wishes to expose/publicize a new shading context to the primary integrator, it should set exposeVol to a non-NULL RixBXLobeTraits pointer (which usually points to the same RixBXLobeTraits passed to the interior's GetNearestHits method). The optional membership array can be used to communicate the subset of points on the current shading context that should be conveyed to the new one. A non-zero value signals the membership request in a new context. If NULL, all points will be used to construct a new shading context. In this usage, the return result will be a distinct shading context appropriate for use by the primary integrator. If exposeVol is NULL, the the result is NULL and internal volume sampling state is released. Callers must be aware that during Begin/EndVolumeSampling the shadingCtx member of the interior integrator associated with this context will be changed to represent the volume contained within the surface. After EndVolumeSampling the shadingCtx will again represent the surface, as was the case before BeginVolumeSampling is called.

virtual RixShadingContext* RixShadingContext::CreateMutableContext ( ) const
pure virtual

Create a context that can be mutated (implements SetBuiltinVar) for the purposes of super sampling a pattern network. The mutable context is created in the Bxdf memory of its parent context and does not need to be released. It will be automatically reclaimed when its parent context is released.

template<class T >
RixSCDetail RixShadingContext::EvalAndCopyParam ( RtInt  id,
RtInt  arrayindex,
T **  result,
T const *  dflt = NULL,
bool  promoteToVarying = false,
MemCategory  mcat = k_BxdfMem 
) const

EvalAnCopyParam: Templated convenience routine for callers who need to modify input parameters. Use with care as it incurs an additional memory allocation and memcpy. NB: only a subset of types produced meaningfully writable results. RtConstStrings, RixBxdfFactory are not among them.

virtual RixSCDetail RixShadingContext::EvalParam ( RtInt  id,
RtInt  arrayindex,
RtInt const **  result,
RtInt const *  dflt = NULL,
bool  promoteToVarying = false 
) const
pure virtual


Id-based parameter evaluation captures the data flow through graph of connected RixPattern and RixBxdf nodes.

A parameter can be constant or computed. Calls to the Eval method of non-constant parameters may trigger function evaluation. Parameter values may be cached by the renderer for the duration of an execution context (see RixBxdf Begin/End).

Calls to EvalParam must fill an entire ShadingContext of values. The exception to this rule is for RixBxdf composition where a RixBxdf may be obtained. In that case, the 'driver' Bxdf is expected to distribute Begin/Eval/Generate/End messages to subservient Bxdf instances.

Parameter evaluation: Bxdfs and Patterns invoke EvalParam to sample their inputs. Since inputs may or may not obtain values from upstream, the detail, obtained via GetParamInfo, can be consulted to hoist expensive computations out of per-point loops. Again, caller is expected to know the type of its parameters. If the optional EvalParam parameter, promoteToVarying is true, then the detail of the result is guaranteed to be k_RixSCVarying but the returned detail will be that associated with the actual connection state. EvalParam works for array elements as well as simple parameters. In the simple-case, set arrayindex to -1. Result is const and should usually not be overwritten by by caller.. It's common for Bxdf's to wish to conform (clamp) their inputs to reasonable ranges and this can be done only in bxdf nodes and only by const_cast-ing. If a value can't be obtained via the network nor the Ri parameterlist, we fill the result with the default value provided. If the dflt value isn't provided we return RixSCInvalidDetail.

virtual RixShadingContext const* RixShadingContext::GetContextById ( RixShadingContext::Id  sctxId) const
pure virtual

GetShadingContextById, given a RixShadingContext::Id, returns a reference to the shading context which has a matching Id, or NULL if no such context can be found. It is the responsibility of the integrator and the caller to ensure that the shading context has not been returned to the system via RixIntegratorContext::ReleaseShadingContexts.

virtual RixDisplayServices* RixShadingContext::GetDisplayServices ( int  version = 1) const
pure virtual

Get access to the display services. This is the same display service normally offered by the integrator context but is provided here to allow RixPatterns and RixBXDFs to bypass the integrator and write directly into AOV channels for special effects.

virtual void RixShadingContext::GetLightEmission ( RtColorRGB *  e) const
pure virtual

GetLightEmission: returns the sampled emission associated with the shading points. Nonzero return values are only expected if the shading context is asssociated with a direct light source. This should not be confused with the results of the LocalEmission of a Bsdf, but might overlap as with PxrLightEmission.

virtual void RixShadingContext::GetNearestHits ( RtInt  numRays,
RtRayGeometry const *  rays,
RtHitPoint *  hits,
char const *  subset = NULL,
RtHitSides  hitSides = k_SidesBoth 
) const
pure virtual

GetNearestHits: traces rays to determine the nearest hit in the given direction. Both arrays must be at least numRays long. Misses are indicated in the RtHitPoint via hits[i].dist == 0. An optional trace subset can be provided to further constrain objects considered. Clients should include RixIntegrator.h for the definition of RtRayGeometry and RtHitPoint structs.

virtual std::vector<const RixShadingContext *> const* RixShadingContext::GetOverlappingVolumes ( ) const
pure virtual

Returns a list of shading contexts associated with any overlapping volumes.

virtual RtInt RixShadingContext::GetParamId ( char const *  name,
RtInt *  paramid 
) const
pure virtual

GetParamId maps a string name to a more efficient integer reference. The paramid may be negative to support dynamic inputs. Non-negative values are indices into the parameter table, while negative values are interpretted as indices into the parameterlist of a RIB instance. Returns 0 on success, returns nonzero if named parameter is not found.

virtual RtInt RixShadingContext::GetParamInfo ( RtInt  paramid,
RixSCType *  type,
RixSCConnectionInfo *  cinfo,
int *  arraylength = NULL 
) const
pure virtual

GetParamInfo returns additional detail about the parameter. It's primary use is during pattern-graph execution to determine connectivity or dynamic array sizes. Returns 0 on success, nonzero on failure.

RtInt RixShadingContext::GetParamInfo ( RtInt  paramid,
RixSCType *  type,
bool *  isconnected,
int *  arraylength = NULL 
) const

This version of GetParamInfo is a convenience for use-cases where a bool notion of connection is sufficient.

virtual RixShadingContext const* RixShadingContext::GetPrimaryContext ( ) const
pure virtual

GetPrimaryContext returns a reference to the (immutable) primary shading context. Only in a case where the caller is operating on a mutable context created by a downstream node should the returned value differ from the invoking ShadingContext.

virtual RixSCDetail RixShadingContext::GetPrimVar ( char const *  name,
RixSCType *  type,
RtInt *  arraylen 
) const
pure virtual

GetPrimVar: lazily evaluates the named primitive variable. Caller is expected to know the datatype in advance and invoke the correct variant. The first variant can be used to efficiently query the existence, type and arraylength of an primvar. The optional radius parameter is filled with an approximate isotropic filter radius associated with the projected ray differentials of each shading point. If the primvar cannot be found, the return value is initialized with the fill value and the return value is k_RixSCInvalidDetail.

virtual RixSCDetail RixShadingContext::GetPrimVar ( char const *  name,
RtFloat const **  var,
RtFloat const **  dXdu,
RtFloat const **  dXdv 
) const
pure virtual

This variant of GetPrimVar produces uni/bi/trivariate derivatives of an arbitrary primvar across the surface measured with respect to u and v. This function is useful in unusual geometric supersampling conditions and for bump mapping. The simpler variant is preferred over this method unless the special features are required.

virtual int RixShadingContext::GetTransform ( char const *  fromSpace,
char const *  toSpace,
RtMatrix4x4 const **  matrix,
int *  numMatrices 
) const
pure virtual

Return an array of matrices numPts in size that represents the transformation from "fromSpace" to "toSpace". If the transformation is time varying, the numMatrices returned will be the same as numPts in the RixShadingContext. If the transformation is uniform, numMatrices will be set to 1. Zero is returned on success.

virtual bool RixShadingContext::HasVolume ( RixSCVolumeSelector  ) const
pure virtual

Support for volume integration:

Begin/EndVolume: can be called by primary integrators to acquire a volume integrator for the selected volume subset (incident or opposite). Depending on the ray path and the requirements of the volume integrator itself, the resulting volume integrator may be bound to a different shading context that was associated with the originating rays. For this reason the incoming ray geometries must be non-const, their shadingCtxIndex may change.

template<class T >
T* RixShadingContext::New ( size_t  nObjs,
MemCategory  cat = k_BxdfMem 
) const

New is a utility (fully inlined) non-virtual method to assist with tedious memory allocation tasks. Note that class-constructor methods may be run on array entries. This cost should be carefully considered for high performance requirements.

virtual void RixShadingContext::SetBuiltinVar ( BuiltinVar  ,
RtFloat *  var 
pure virtual

Useful for perturbing a context for things such as bump mapping. (eg. jittering u,v,w within the du,dv,dw neighborhood).

virtual void RixShadingContext::SetPrimVar ( char const *  name,
RixSCDetail  d,
RtFloat *  var,
RtFloat *  radius 
pure virtual

SetPrimVar: useful for changing state on mutable shading contexts for consumption by upstream pattern-graph nodes.

virtual int RixShadingContext::Transform ( TransformInterpretation  interp,
char const *  fromSpace,
char const *  toSpace,
RtFloat3 *  var,
RtFloat *  radius = NULL 
) const
pure virtual

Transform an array of RtFloat3 (and optional radius) the same size as the numPts in the RixShadingContext. The type of transformation is specified with TransformInterpretation. If the call is successful it will return 0.

Member Data Documentation

RixBsdf* RixShadingContext::bsdf

The bsdf shader is non-NULL for radiance queries and is responsible for computing light scattering.

RtInt* RixShadingContext::integratorCtxIndex

integratorCtxIndex maps indices to varying ShadingContext entries to the index associated with IntegratorContext. The ith element of our integratorCtxIndex tells us the index of the associated primaryRay and other subsidiary channels. The integratorCtxIndex is critical for proper integrator functionality and should be considered "opaque" to the Bxdf.

RtInt RixShadingContext::numPts

numPts is the number of shading points. All other non-uniform values can be assumed to have this length.

RtInt* RixShadingContext::rayId

rayId is similar to integratorCtxIndex. This array can be used by integrators to track a correspondence between the ShadingContext entries and integrator-specific data structures. The rayId may be critical for proper functionality of a given integrator and should be considered "opaque" to the Bxdf.

struct { ... } RixShadingContext::scTraits

shadingCtxTraits conveys a variety of (uniform) ShadingContex traits to shader and integrator.

RixSCShadingMode RixShadingContext::shadingMode

true if we're operating on a reyes grid this may occur in a variety of caching conditions shadingMode contains the current mode of operation associated with this shading context.

RtColorRGB* RixShadingContext::transmission

transmission is a per-point transmission that is associated with the ray that produced the associated hit. It's used by interiors and volumes to "occlude" the results of the radiance computation of each point.

The documentation for this class was generated from the following file: