HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
BRAY_PixelOracle.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: BRAY_PixelOracle.h (BRAY Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __BRAY_PixelOracle__
12 #define __BRAY_PixelOracle__
13 
14 #include "BRAY_API.h"
15 #include "BRAY_Interface.h"
16 #include "BRAY_SampleFilter.h"
17 #include <SYS/SYS_Hash.h>
18 #include <UT/UT_UniquePtr.h>
19 #include <UT/UT_Rect.h>
20 
21 class BRAY_PixelState;
22 class BRAY_FilterInit;
23 class UT_Options;
24 class UT_StringArray;
25 
26 extern "C" {
27  SYS_VISIBILITY_EXPORT extern void newBRAYPixelOracle(void *);
28 }
29 
30 /// A Pixel Oracle is responsible for detemining which pixels should be sampled
31 /// within a tile.
33 {
34 public:
36  {
37  public:
38  virtual ~Factory();
40  instance(const UT_Options *args) const = 0;
41  };
43 
44  /// @{
45  /// Factory access
46  static void listFactories(UT_StringArray &result);
47  static void registerPlugin(const UT_StringHolder &name, FactoryPtr factory);
48  static UT_UniquePtr<BRAY_PixelOracle> instancePlugin(
49  const UT_StringRef &style,
50  const UT_Options *options);
51  static void releasePlugin(UT_UniquePtr<BRAY_PixelOracle> p);
52  static void freePluginCache();
53  /// @}
54 
56  virtual ~BRAY_PixelOracle();
57 
58  /// Class name of the oracle
59  virtual const char *className() const = 0;
60 
61  /// Fill out the pixels which need to be sampled, returning the number of
62  /// pixels filled out. The @c pixels buffer is guaranteed to have at least
63  /// rect.width()*rect.height() entries. The function should return the
64  /// number of samples filled out. Each pixel should be inside the bounding
65  /// rectangle.
66  ///
67  /// The oracle is free to return a smaller number of rays. It's also
68  /// possible to send multiple rays for a single pixel.
69  ///
70  /// The default method will send one ray per pixel and is somewhat similar
71  /// to @code
72  /// for (int y = rect.y(), ye = rect.y2e(); y < ye; ++y)
73  /// for (int x = rect.x(), xe = rect.x2e(); x < xe; ++x, ++pixels)
74  /// *pixels = UT_Vector2i(x, y);
75  /// return rect.width()*rect.height();
76  /// @endcode
77  ///
78  virtual size_t fillPixels(BRAY_PixelState &pstate,
79  const UT_DimRect &rect,
81 
82  /// Method used to initialize the oracle. This will be called prior to
83  /// each render (oracles should clear any buffers on subsequent renders).
84  ///
85  /// Note that sample filters are @b not cleared between subsequent renders,
86  /// so if the oracle creates a sample filter, it should be persistent
87  /// between runs.
88  virtual bool initializeOracle(BRAY_FilterInit &init,
89  int xres, int yres,
90  const UT_StringArray &aov_names,
91  const UT_IntArray &aov_sizes) = 0;
92 
93  /// Return the hash of the arguments for this filter
94  SYS_HashType optionsHash() const { return myOptionsHash; }
95 
96  /// Sometimes an oracle can be more efficient when tied to a sampling
97  /// filter. This method allows an oracle to create a sampling filter to
98  /// keep track of samples written to the image. This method is called @b
99  /// after @c initializeOracle().
100  ///
101  /// If the oracle creates a sample filter, it should make sure to call @c
102  /// BRAY_SampleFilter::initialize() on the created sample filter.
103  virtual BRAY_SampleFilterPtr sampleFilter(BRAY_FilterInit &init,
104  const UT_StringArray &all_aovs)
105  { return BRAY_SampleFilterPtr(); }
106 
107  /// The checkpoint function is called to save the state of the pixel filter
108  /// to a checkpoint file.
109  ///
110  /// The default method prints a warning that checkpointing isn't supported
111  /// and fails.
112  virtual bool checkpoint(UT_JSONWriter &w) const = 0;
113 
114  /// @c loadCheckpoint is called to restore the state of the pixel filter.
115  /// In theory, all the settings for the pixel filter should match. Only
116  /// per-pixel data should be different.
117  virtual bool loadCheckpoint(UT_JSONParser &p);
118 
119 protected:
120  /// Read a pixel from a given AOV. The aov_index should be the index into
121  /// the @c aovnames that was passed into @c initializeOracle() (or the
122  /// index returned by @c addAOV());
123  ///
124  /// For greater efficiency, consider creating a paired SampleFilter.
125  const float *readPixel(const BRAY_PixelState &pstate,
126  int aov_index, int px, int py) const;
127 
128  /// Return a random number. The sequence of random numbers will be
129  /// consistent for every render, regardless of threading order.
130  ///
131  /// The random functions use the same internal state so they should be
132  /// called consistently.
133  float randomF(BRAY_PixelState &pstate) const;
134 
135  /// Return an integer random number. This can be used as a seed if
136  /// multiple random numbers need to be generated. The sequence of random
137  /// numbers will be conssitent for every render, regardless of threading
138  /// order.
139  ///
140  /// The random functions use the same internal state so they should be
141  /// called consistently.
142  uint randomI(BRAY_PixelState &pstate) const;
143 
144  /// If the oracle needs an additional AOV, you can call this method during
145  /// initializeOracle(). The function returns the index of the new AOV (or
146  /// -1 on failure). If there are errors, the messages will be printed out
147  /// to UT_ErrorLog.
148  ///
149  /// If options are required, they can be initialized by planeProperties()
150  /// Passing in an empty OptionSet is legal.
151  int addAOV(BRAY_FilterInit &init,
152  const UT_StringHolder &name,
153  const UT_StringHolder &var,
154  int tuple_size,
155  const BRAY::OptionSet &options);
156 
157  /// Create an option set before adding creating an extra AOV
158  BRAY::OptionSet planeProperties(BRAY_FilterInit &init) const;
159 private:
160  SYS_HashType myOptionsHash;
161 };
162 
164 
165 #endif
virtual BRAY_SampleFilterPtr sampleFilter(BRAY_FilterInit &init, const UT_StringArray &all_aovs)
SYS_VISIBILITY_EXPORT void newBRAYPixelOracle(void *)
SYS_HashType optionsHash() const
Return the hash of the arguments for this filter.
#define SYS_VISIBILITY_EXPORT
UT_UniquePtr< BRAY_SampleFilter > BRAY_SampleFilterPtr
std::size_t SYS_HashType
Define the type for hash values.
Definition: SYS_Hash.h:19
JSON reader class which handles parsing of JSON or bJSON files.
Definition: UT_JSONParser.h:76
Class which writes ASCII or binary JSON streams.
Definition: UT_JSONWriter.h:35
GLuint const GLchar * name
Definition: glcorearb.h:785
UT_UniquePtr< BRAY_PixelOracle > BRAY_PixelOraclePtr
std::unique_ptr< T, Deleter > UT_UniquePtr
A smart pointer for unique ownership of dynamically allocated objects.
Definition: UT_UniquePtr.h:33
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:856
GLuint64EXT * result
Definition: glew.h:14311
GLfloat GLfloat p
Definition: glew.h:16656
IFDmantra py
Definition: HDK_Image.dox:266
A map of string to various well defined value types.
Definition: UT_Options.h:84
#define BRAY_API
Definition: BRAY_API.h:12
UT_UniquePtr< Factory > FactoryPtr
**If you just want to fire and args
Definition: thread.h:615
unsigned int uint
Definition: SYS_Types.h:45
GLint GLint GLsizei GLint GLenum GLenum const void * pixels
Definition: glcorearb.h:107