RenderMan  26.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
RixLighting.h
Go to the documentation of this file.
1 /*
2 # ------------------------------------------------------------------------------
3 #
4 # Copyright (c) 2021 Pixar. All rights reserved.
5 #
6 # The information in this file (the "Software") is provided for the exclusive
7 # use of the software licensees of Pixar ("Licensees"). Licensees have the
8 # right to incorporate the Software into other products for use by other
9 # authorized software licensees of Pixar, without fee. Except as expressly
10 # permitted herein, the Software may not be disclosed to third parties, copied
11 # or duplicated in any form, in whole or in part, without the prior written
12 # permission of Pixar.
13 #
14 # The copyright notices in the Software and this entire statement, including the
15 # above license grant, this restriction and the following disclaimer, must be
16 # included in all copies of the Software, in whole or in part, and all permitted
17 # derivative works of the Software, unless such copies or derivative works are
18 # solely in the form of machine-executable object code generated by a source
19 # language processor.
20 #
21 # PIXAR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
22 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL PIXAR BE
23 # LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
24 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
25 # OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
26 # CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. IN NO CASE WILL
27 # PIXAR'S TOTAL LIABILITY FOR ALL DAMAGES ARISING OUT OF OR IN CONNECTION WITH
28 # THE USE OR PERFORMANCE OF THIS SOFTWARE EXCEED $50.
29 #
30 # Pixar
31 # 1200 Park Ave
32 # Emeryville CA 94608
33 #
34 # ------------------------------------------------------------------------------
35 */
36 
37 #ifndef RixLighting_h
38 #define RixLighting_h
39 
40 #include "RixBxdf.h" // for RixBXEvaluateDomain, etc
41 #include "RixInterfaces.h" // for RixInterface
42 #include "RiTypesHelper.h" // for RtVector3, RtPoint3
43 
44 class RixPhotonGuiding;
45 class RixRNG;
46 class RixShadingContext;
47 struct RixMWConnectionResult;
48 struct RixBXLobeSampled;
49 struct RixBXLobeTraits;
50 struct RixBXLobeWeights;
51 
142 class RixLightingServices : public RixInterface
143 {
144 public:
145  RixLightingServices() : RixInterface(1), shadingCtx(nullptr), domain(k_RixBXBoth)
146  {}
147 
148  // Local lighting (shading context aware and importance sampled)
149  enum IntegratorIntent
150  {
151  k_LightSamples,
152  k_MaterialSamples,
153  k_MaterialAndLightSamples
154  };
155 
171  enum FixedSampleCountMode
172  {
173  k_IgnoreFixedSampleCount = 0,
174  k_RespectFixedSampleCount = 1,
175  k_ReducedFixedSampleCount = 2
176  };
177  typedef FixedSampleCountMode Mode; // for backward compatibility
178 
182  class SampleMode
183  {
184  public:
185  enum Mode
186  {
187  k_forPoint,
188  k_forLineSegment
189  };
190 
191  Mode mode;
192 
193  SampleMode() : mode(k_forPoint){};
194  };
195 
196  struct IndirectResult
197  {
198 
199  IndirectResult() : learningNode(nullptr), bxdfResponse(0.0f), id(0), faceIdx(0), radianceIn(0.0f), transmission(1.0f), hasResults(false) {}
200 
201  IndirectResult(void* _learningNode, const RtPoint3& _currP, const RtPoint3& _camP, float _r, const RtVector3& _wo, float _bxdfResponse, int _id, int _f)
202  : learningNode(_learningNode), currP(_currP), camP(_camP), nodeR(_r), wo(_wo), hitP(0.0f, 0.0f, 0.0f), bxdfResponse(_bxdfResponse), id(_id), faceIdx(_f), radianceIn(0.0f), transmission(1.0f), hasResults(false) {}
203 
204  void AddRadiance(float r)
205  {
206  radianceIn += r;
207  }
208 
209  void UpdateHitP(RtPoint3 const& p)
210  {
211  hitP = p;
212  hasResults = true;
213  }
214 
215  void* learningNode;
216  RtPoint3 currP;
217  RtPoint3 camP;
218  float nodeR;
219  RtVector3 wo;
220  RtPoint3 hitP;
221  float bxdfResponse;
222  int id;
223  int faceIdx;
224  float radianceIn;
225  float transmission;
226  bool hasResults;
227  };
228 
259  virtual void Begin(
260  // inputs
261  RixShadingContext const* shadingContext, RixRNG* rixRNG,
262  RixBXEvaluateDomain evaluationDomain, IntegratorIntent integratorIntent,
263  FixedSampleCountMode fixedSampleCountMode, SampleMode sampleMode,
264  // outputs
265  int* fixedSampleCount = nullptr,
266  // inputs
267  int depth = 0, int parentIndirectCount = 1) = 0;
268 
358  virtual void GenerateSamples(
359  // Pointer parameters that represent arrays are expected to either be of size:
360  // - numPts (#1) or
361  // - numPts * numLightSamples (#2)
362  int numLightSamples, RixRNG* rixRNG,
363 
364  // outputs
365  int* lightGroupIds, // #2
366  RixLPEToken* lightLpeTokens, // #2
367  RtVector3* directionsToSamples, // #2
368  RtNormal3* lightNormals, // #2
369  float* distancesToSamples, // #2
370  RixBXLobeWeights* lightContributions,
371 
372  RtColorRGB* transmissions, // #2, optional
373  RtColorRGB* volumeEmissions, // #2, optional
374  float* directLightingPdfs, // #2
375  float* selectionProbs, // #2
376  // inputs
377  RixBXLobeTraits const* materialLobesWanted, // #1, optional
378 
379  // outputs
380  RixBXLobeWeights* evaluatedMaterialWeights, // optional
381  float* evaluatedMaterialFPdfs, // #2, optional
382  float* evaluatedMaterialRPdfs, // #2, optional
383  RixBXLobeTraits* evaluatedMaterialLobes, // #2, optional
384 
385  RixLight** sampledLights, // #2, optional
386 
387  // inputs
388  RtColorRGB const* pathThroughputs = nullptr, // #1, optional
389  RixMWConnectionResult* mwConnectionResult = nullptr // optional
390  ) = 0;
391 
441  virtual void GenerateSamples(
442  // Pointer parameters that represent arrays are expected to either be of size:
443  // - numPts (#1) or
444  // - numPts * numLightSamples (#2)
445  // inputs
446  int numLightSamples, RixRNG* rixRNG,
447 
448  // outputs
449  int* lightGroupIds, // #2
450  RixLPEToken* lightLpeTokens, // #2
451  RtVector3* directionsToSamples, // #2
452  RtNormal3* lightNormals, // #2
453  float* distancesToSamples, // #2
454  RixBXLobeWeights* lightContributions,
455 
456  RtColorRGB* transmissions, // #2, optional
457  RtColorRGB* volumeEmissions, // #2, optional
458  float* directLightingPdfs, // #2
459  float* selectionProbs, // #2
460 
461  float* emissionPositionPdfs, // #2
462  float* emissionDirectionPdfs, // #2, FLT_MAX for infinite lights
463  float* solidAngleToAreaFactors, // #2, 1.0f for infinite lights
464 
465  // inputs
466  RixBXLobeTraits const* materialLobesWanted, // #1, optional
467 
468  // outputs
469  RixBXLobeWeights* evaluatedMaterialWeights, // optional
470  float* evaluatedMaterialFPdfs, // #2, optional
471  float* evaluatedMaterialRPdfs, // #2, optional
472  RixBXLobeTraits* evaluatedMaterialLobes, // #2, optional
473 
474  RixLight** sampledLights, // #2, optional
475 
476  // inputs
477  RtColorRGB const* pathThroughputs = nullptr, // #1, optional
478 
479  RixPhotonGuiding const* photonGuide = nullptr, // optional
480 
481  RixMWConnectionResult* mwConnectionResult = nullptr // optional
482  ) = 0;
483 
506  virtual void GenerateSamplesForRaySegments(
507  int numLightSamples,
508  // Pointer parameters that represent arrays are expected to be of size numPts
509  RixRNG* rixRNG, float* maxDistances, RtVector3* samplePositions, float* selectionProbs,
510  float* segmentMinT, float* segmentMaxT) = 0;
511 
589  virtual void EvaluateSamples(
590  // Pointer parameters that represent arrays are expected to either be of size:
591  // - numPts (#1) or
592  // - numPts * numMaterialSamples (#2)
593  // inputs
594  int numMaterialSamples, RixRNG* rixRNG,
595  RtVector3 const* directions, // #2
596 
597  // input/output
598  float* distances, // #2
599 
600  // inputs
601  float const* materialPdfs, // #2
602  RixBXLobeWeights const* materialWeights,
603  RixBXLobeSampled const* materialLobeSampled, // #2
604 
605  // outputs
606  int* lightGroupIds, // #2
607  RixLPEToken* lightLpeTokens, // #2
608  RixBXLobeWeights* lightContributions,
609  RtColorRGB* transmissions, // #2, optional
610  RtColorRGB* volumeEmissions, // #2, optional
611  float* directLightingPdfs, // #2
612  float* selectionProbs, // #2
613  RtNormal3* lightNormals, // #2
614 
615  RixLight** evaluatedLights, // #2, optional
616 
617  // inputs
618  RtColorRGB const* pathThroughputs = nullptr // #1, optional
619  ) = 0;
620 
621  // Bidirectional
668  virtual void EvaluateSamples(
669  // Pointer parameters that represent arrays are expected to either be of size:
670  // - numPts (#1) or
671  // - numPts * numMaterialSamples (#2)
672  // inputs
673  int numMaterialSamples, RixRNG* rixRNG,
674  RtVector3 const* directions, // #2
675 
676  // input/output
677  float* distances, // #2
678 
679  // inputs
680  float const* materialPdfs, // #2
681  RixBXLobeWeights const* materialWeights,
682  RixBXLobeSampled const* materialLobeSampled, // #2
683 
684  // outputs
685  int* lightGroupIds, // #2
686  RixLPEToken* lightLpeTokens, // #2
687  RixBXLobeWeights* lightContributions,
688  RtColorRGB* transmissions, // #2, optional
689  RtColorRGB* volumeEmissions, // #2, optional
690  float* directLightingPdfs, // #2
691  float* selectionProbs, // #2
692 
693  float* emissionPositionPdfs, // #2
694  float* emissionDirectionPdfs, // #2, FLT_MAX for infinite lights
695  float* solidAngleToAreaFactors, // #2, 1.0f for infinite lights
696 
697  RtNormal3* lightNormals,
698 
699  RixLight** evaluatedLights, // #2, optional
700 
701  // inputs
702  RtColorRGB const* pathThroughputs = nullptr, // #1, optional
703 
704  RixPhotonGuiding const* photonGuide = nullptr // optional
705  ) = 0;
706 
707  // Global lighting / emission for "photons"
719  virtual void BeginEmission(FixedSampleCountMode mode, int* fixedSampleCount = nullptr) = 0;
720 
846  virtual void GenerateEmission(
847  // Pointer parameters that represent arrays are expected to either be of size:
848  // - numPts (#1) or
849  // - numPts * numSamples (#2)
850  // inputs
851  int numPts,
852  int const* integratorContextIndices, // #1
853  int const* rayIds, // #2
854  int numSamples, RixRNG* rixRNG,
855 
856  // outputs
857  int* lightGroupIds, // #2
858  RixLPEToken* lightLpeTokens, // #2
859  RixBXLobeWeights* lightContributions, // #2
860 
861  RtColorRGB* transmissions, // #2
862  RtColorRGB* volumeEmissions, // #2
863 
864  int* numShadingContexts, // #1
865  RixShadingContext const*** shadingContexts, // See method description
866  RtPoint3* emissionPositions, // #2
867  RtVector3* emissionNormals, // #2
868 
869  float* distances, // #2
870  float* directLightingPdfs, // #2
871  float* selectionProbs, // #2
872  float* emissionPositionsPdfs, // #2
873  RtVector3* emissionDirections, // #2
874  float* emissionCosines, // #2
875  float* emissionDirectionPdfs, // #2
876  float* solidAngleToAreaFactors, // #2
877 
878  // inputs
879  RixPhotonGuiding const* photonGuide = nullptr // optional
880  ) = 0;
881 
885  virtual void End() = 0;
886 
890  virtual void EndEmission() = 0;
891 
892  // All the following methods are callable after RixIntegrator::Begin
893 
895  virtual int GetNumLightGroups() = 0;
897  virtual int GetLightGroup(RtUString const name) = 0;
899  virtual RtUString GetLightGroupName(int i) = 0;
900 
902  virtual int GetTotalNumLights() = 0;
904  virtual int GetTotalNumLightsWithFixedSamples() = 0;
906  virtual int GetTotalFixedSamples() = 0;
907 
911  virtual void UpdateWithResults(int nSamples, RixBXLobeWeights const* contribution,
912  RtColorRGB const* trans, float const* lPdfDirect,
913  float const* lightSelectionProbs, float const* distances,
914  RixBXLobeWeights const* evaluatedMaterialWeights,
915  const RixLight* const* lights) = 0;
916 
921  virtual void IrradianceEstimate(uint32_t lightSetId, RtPoint3 const* points, int numPts,
922  float* estimates, float* confidences) = 0;
923 
924  virtual void UpdateIndirectPaths(const std::vector<IndirectResult>* indirectResults, int numPaths) = 0;
925 
926  virtual void EvalIndirect(int const* rayIds, int numPts, const RtVector3* wos, void** learningNodes, const int* faceIdx, const RtNormal3* pNn, const RixBXLobeTraits* lobesWanted, float* pdfs, float* vals) = 0;
927 
928  virtual void SampleIndirect(int const* rayIds, int numPts,
929  RixRNG* rixRNG,
930  const RtVector3* pNgn,
931  const RtVector3* pVn, const RtNormal3* pNn, int* sampleFlags,
932  RtVector3* wos, float* pdfs, float* confidences,
933  void** learningNodes,
934  int* faceIdxs, RtPoint3* camPs, float* nodeRs, float* vals) = 0;
935 
936  // (end)
937 
938 
939 protected:
940  virtual ~RixLightingServices()
941  {}
942  RixShadingContext const* shadingCtx;
943  RixBXEvaluateDomain domain;
944 };
945 
946 #endif