HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
BRAY_Procedural.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_Procedural.h (BRAY Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __BRAY_Procedural__
12 #define __BRAY_Procedural__
13 
14 #include "BRAY_API.h"
15 #include "BRAY_AttribList.h"
16 #include "BRAY_Interface.h"
17 
18 class UT_JSONWriter;
20 
22 {
23 public:
24  /// Templatized on <fpreal32> or <fpreal64>
25  /// This structure is used in the intersect() function to compute an
26  /// intersection with the procedural primitive.
27  template <typename PREC>
28  struct Ray
29  {
30  // RayType
35  };
38 
39  /// This class stores information about the hit. The information is passed
40  /// back to the procedural primitive when evaluating attributes.
41  /// The procedural object can store any data it wants in the @c u, @c v,
42  /// @c w and @c prim_id fields. These are passed through to the primitive
43  /// when looking up shading variables/attributes. At the current time,
44  /// @c prim_id must be >= 0.
45  ///
46  /// When the ray hits, the procedural should fill out
47  /// - @c distance : the distance from the origin to the hit point
48  /// - @c zback : For volume primitives, @c distance represents the start of
49  /// the shading interval while @c zback represents the farthest extent of
50  /// the shading sample, so for volumes, @zback should be >= @distance.
51  /// For non-volume shading information, @zback should be left at 0.
52  /// - @c Ng : The geometric normal at the hit surface
53  struct Hit
54  {
56  : distance(d)
57  , zback(0)
58  , prim_id(0)
59  {
60  }
61  fpreal distance; // Distance to hit
62  fpreal zback; // Distance to zback (0: solid surface)
63  fpreal u, v, w; // Parametric coordinates
64  UT_Vector3 Ng; // Geometric normal
65  uint prim_id; // ID of primitive in procedural
66  };
67 
69  virtual ~BRAY_Procedural();
70 
71  /// Return a name for this procedural. This defaults to factory()->name();
72  virtual const char *className() const;
73 
74  /// Return the factory definition
75  virtual const BRAY_ProceduralFactory *factory() const = 0;
76 
77  /// Return an attribute list for the attributes supported by this primitive.
78  virtual const BRAY_AttribList *attribList() const = 0;
79 
80  /// Return a parameter list that the procedural exposes to the outside
81  /// world that could be set using the @c setParameter() methods
82  /// The default implementation calls factory()->paramList();
83  virtual const BRAY_AttribList *paramList() const;
84 
85  /// Return the bounding box for the object at a given time
86  virtual void bounds(UT_BoundingBox &bounds, BRAYtime time) const = 0;
87 
88  /// @{
89  /// Set parameters on procedurals in addition to attributes that the
90  /// procedural might provide. One way to think of parameters and attributes
91  /// is that attributes are what procedurals bring to the table internally,
92  /// where as parameters are something that can be applied onto procedurals.
93  /// For example, a 'Sphere' object is a procedural. It's attributes could
94  /// be like 'color', 'normal' on vertices. whereas 'parameters' could be
95  /// 'radius', etc. Depending upon the procedural the meaning of these two
96  /// terms change contextually.
97  ///
98  /// The templates are specialized for:
99  /// - int32, int64, fpreal32, fpreal64, UT_StringHolder
100  template <typename T>
101  void setParameter(const UT_StringRef &key, const T &val)
102  {
103  doSetParameter(key, &val, 1);
104  }
105 
106  template <typename T>
107  void setParameter(const UT_StringRef& key, const T* values, int n)
108  {
109  doSetParameter(key, values, n);
110  }
111  /// @}
112 
113  /// @{
114  /// Signal the procedural
115  ///
116  /// We allow for the Procedural to update itself and do any further
117  /// processing in case any parameters have been set. The set parameter
118  /// methods are generally invoked on the procedural, which might be
119  /// implemented by the procedural to copy data, precompute stuff, validate
120  /// parameter ranges etc. Once these have been set, the begin/end update
121  /// methods can be used by the procedural to perform operations that can be
122  /// performed only when there's nothing more to set as parameters to the
123  /// procedural. The procedural can now start working on doing other things
124  /// with the set parameters because it can be sure that the parameters now
125  /// have become immutable.
126  void beginUpdate()
127  {
128  doBeginUpdate();
129  }
130 
131  void endUpdate()
132  {
133  doEndUpdate();
134  }
135  /// @}
136 
137  /// Check whether the procedural is valid
138  bool isValid() const
139  {
140  return checkIsValid();
141  }
142 
143  /// @{
144  /// Perform ray-intersection
145  ///
146  /// If the distanct to the closest intersection point for the procedural
147  /// object is closer than the @c distance already stored in the @c
148  /// hit_info, the hit information should be replaced and the @c intersect()
149  /// method should return @c true.
150  ///
151  /// If the distance to the closest intersection point is farther than the
152  /// existing @c distance, then the @c hit_info should remain unchanged.
153  ///
154  /// NOTE:
155  /// The ray's direction vector CANNOT be expected to be unit length
156  /// Hence the procedural is responsible for accounting and returning
157  /// the correct 't' in the hit_info struct if it ever scaled
158  /// it internally to unit length.
159  virtual bool intersect(const Ray32 &ray, Hit &hit_info) const = 0;
160  virtual bool intersect(const Ray64 &ray, Hit &hit_info) const = 0;
161  /// @}
162 
163  /// Return a display color for low-quality rendering
164  virtual UT_Vector3 displayColor() const { return UT_Vector3(1, 1, 1); }
165 
166  /// @{
167  /// Evaluate an attribute on this primitive. The methods should return a
168  /// pointer to the attribute data. If there isn't a direct raw pointer to
169  /// the data, the buffer passed in can be used to store the data and that
170  /// pointer can be returned.
171  /// The @c element is the element
172  virtual const int32 *attribVal(int attrib, BRAYtime time,
173  const Ray32 &ray, const Hit &hit_info,
174  int32 *buf, int size) const = 0;
175  virtual const int64 *attribVal(int attrib, BRAYtime time,
176  const Ray32 &ray, const Hit &hit_info,
177  int64 *buf, int size) const = 0;
178  virtual const fpreal32 *attribVal(int attrib, BRAYtime time,
179  const Ray32 &ray, const Hit &hit_info,
180  fpreal32 *buf, int size) const = 0;
181  virtual const fpreal64 *attribVal(int attrib, BRAYtime time,
182  const Ray32 &ray, const Hit &hit_info,
183  fpreal64 *buf, int size) const = 0;
184  virtual const UT_StringHolder *attribVal(int attrib, BRAYtime time,
185  const Ray32 &ray, const Hit &hit_info,
186  UT_StringHolder *buf, int size) const = 0;
187 
188 
189  /// @}
190 
191  /// @{
192  /// Evaluation of array attributes (each attribute can have an arbitrary
193  /// number of entries. By default, the array attribute evaluators set the
194  /// arrays to a size of 0 and return the storage array.
195  virtual const UT_ValArray<int32> *attribVal(int attrib,
196  BRAYtime time,
197  const Ray32 &ray,
198  const Hit &hit_info,
200  int size) const;
201  virtual const UT_ValArray<int64> *attribVal(int attrib,
202  BRAYtime time,
203  const Ray32 &ray,
204  const Hit &hit_info,
206  int size) const;
207  virtual const UT_ValArray<fpreal32> *attribVal(int attrib,
208  BRAYtime time,
209  const Ray32 &ray,
210  const Hit &hit_info,
212  int size) const;
213  virtual const UT_ValArray<fpreal64> *attribVal(int attrib,
214  BRAYtime time,
215  const Ray32 &ray,
216  const Hit &hit_info,
218  int size) const;
219  virtual const UT_StringArray *attribVal(int attrib,
220  BRAYtime time,
221  const Ray32 &ray,
222  const Hit &hit_info,
224  int size) const;
225  /// @}
226 
227  /// This method can be used to be notified of changes to the object
228  virtual void update(BRAY_EventType event) = 0;
229 
230  /// Dump out information about the procedural for debugging. By default, a
231  /// null is written to the stream.
232  virtual void dumpInfo(UT_JSONWriter &w) const;
233 
234 protected:
235  /// This method will be called to print out an error if the procedural isn't
236  /// set up properly. You can override it to silence the errors.
237  virtual void errorMessage(const char *fmt, ...)
239 
240  /// These functions are the ones that each procedural will override
241  /// for doing preupdate/post update operations.
242  virtual void doBeginUpdate() = 0;
243  virtual void doEndUpdate() = 0;
244 
245  /// Check to see whether the procedural is valid
246  virtual bool checkIsValid() const = 0;
247 
248  /// These methods will be used by the implementing classes to set
249  /// parameters that the procedural will support
250  virtual void doSetParameter(const UT_StringRef& key,
251  const int32* values, int n = 1) = 0;
252  virtual void doSetParameter(const UT_StringRef& key,
253  const int64* values, int n = 1) = 0;
254  virtual void doSetParameter(const UT_StringRef& key,
255  const fpreal32* values, int n = 1) = 0;
256  virtual void doSetParameter(const UT_StringRef& key,
257  const fpreal64* value, int n = 1) = 0;
258  virtual void doSetParameter(const UT_StringRef& key,
259  const UT_StringHolder* value, int n = 1) = 0;
260 };
261 
262 #endif
BRAY_EventType
Types of events that can be sent as updates to the renderer.
Definition: BRAY_Types.h:39
GLsizeiptr size
Definition: glew.h:1681
int int32
Definition: SYS_Types.h:39
float BRAYtime
Consistent representation of time type within BRAY.
Definition: BRAY_Types.h:472
GT_API const UT_StringHolder time
void setParameter(const UT_StringRef &key, const T &val)
GLuint const GLfloat * val
Definition: glew.h:2794
UT_Vector3T< float > UT_Vector3
GLint GLsizei const GLuint64 * values
Definition: glew.h:3612
bool isValid() const
Check whether the procedural is valid.
void setParameter(const UT_StringRef &key, const T *values, int n)
Class which writes ASCII or binary JSON streams.
Definition: UT_JSONWriter.h:34
const GLdouble * v
Definition: glew.h:1391
3D Vector class.
float fpreal32
Definition: SYS_Types.h:200
virtual UT_Vector3 displayColor() const
Return a display color for low-quality rendering.
double fpreal64
Definition: SYS_Types.h:201
bool intersect(const Line3< T > &line, const Vec3< T > &v0, const Vec3< T > &v1, const Vec3< T > &v2, Vec3< T > &pt, Vec3< T > &barycentric, bool &front)
#define SYS_PRINTF_CHECK_ATTRIBUTE(string_index, first_to_check)
Definition: SYS_Types.h:433
const UT_Vector3T< PREC > & org
GLubyte GLubyte GLubyte GLubyte w
Definition: glew.h:1890
GLsizei n
Definition: glew.h:4040
GLsizei GLsizei GLfloat distance
Definition: glew.h:13640
HGLRC const int * attribList
Definition: wglew.h:140
long long int64
Definition: SYS_Types.h:116
Hit(fpreal d=SYS_FPREAL_MAX)
const UT_Vector3T< PREC > & dir
#define SYS_FPREAL_MAX
Definition: SYS_Types.h:286
cl_event event
Definition: glew.h:3695
Each BRAY_Object can define a list of attributes that it can evaluate.
fpreal64 fpreal
Definition: SYS_Types.h:277
#define BRAY_API
Definition: BRAY_API.h:12
#define const
Definition: zconf.h:214
GLenum GLuint GLsizei const GLchar * buf
Definition: glew.h:2580
GLsizei const GLfloat * value
Definition: glew.h:1849
unsigned int uint
Definition: SYS_Types.h:45