HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
IMG3D_Manager.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: IMG3D_Manager.h ( IMG3D Library, C++)
7  *
8  * COMMENTS: API into the 3D texture library.
9  */
10 
11 #ifndef __IMG3D_Manager__
12 #define __IMG3D_Manager__
13 
14 #include "IMG3D_API.h"
15 #include <SYS/SYS_Types.h>
16 #include <UT/UT_Vector3.h>
17 #include <UT/UT_BoundingBox.h>
18 
19 class UT_String;
20 
21 /// Callback function for evaluating the values of a 3D texture at a particular
22 /// position in space. The callback takes:
23 /// - nvalues = the number of positions to evaluate
24 /// - pos = an array which is nvalues long containing the position to
25 /// evaluate.
26 /// - result = an array whose size is <tt>nvalues * sum(ch_size)</tt> long.
27 /// The resulting values should be interleaved. That is, all the
28 /// channel values for the first position, then all the channel
29 /// values for the second position, etc.
30 /// - ch_name = The array of channel names being evaluated
31 /// - ch_size = The array of channel sizes being evaluated.
32 /// - for_aa = Whether the samples being evaluated are primary or
33 /// anti-aliasing samples.
34 typedef void (*IMG3D_TextureEval)(int nvalues,
35  const UT_Vector3 *pos,
36  fpreal32 *result[],
37  const char *names[],
38  int sizes[],
39  int for_aa);
40 
41 typedef void (*IMG3D_Manager_Eval)(int nvalues,
42  const fpreal32 *pos,
43  fpreal32 *result[],
44  const char *names[],
45  int sizes[],
46  int for_aa);
47 
48 /// @brief Class to handle reading/writing 3D texture images
49 ///
50 /// A 3D texture file is similar to a 2D texture file, but with an added
51 /// dimension. The 3D texture is broken down into 3D tiles. Each tile is
52 /// stored independently in the file. This allows for partial loading of the
53 /// 3D texture (without having to load the entire image at one time).
54 ///
55 /// However, the tiled approach makes it difficult to create images since the
56 /// writer works on a single tile at a time.
57 ///
58 /// Just like image files, the 3D texture file can have an arbitrary number of
59 /// channels, each with its own name, storage and tuple size.
60 ///
61 /// In order to read an 3D texture, you have to open both an image and a
62 /// channel: @code
63 /// IMG3D_Manager fp;
64 /// int channel_index;
65 /// fp.openTexture(filename);
66 /// fp.openChannel(channel);
67 /// @endcode
69 public:
70  IMG3D_Manager();
71  ~IMG3D_Manager();
72 
73  /// Close the file (whether opened for read or write).
74  /// This is done automatically on destruction.
75  int closeTexture();
76 
77 public:
78  /// Open a texture for reading. Returns 0 if there was an error opening
79  /// the file.
80  int openTexture(const char *filename);
81 
82  // Query functions, require the texture to be open (and specified
83  // channel indices to exist)
84 
85  // Size of the bounding box of the i3d.
86  // Null will be returned if the file has not been opened.
87 
88  /// Returns an array of 3 floats for xmin(), ymin(), zmin() representing
89  /// the left, bottom, front corner of the 3D texture.
90  const float *getCorner() const; // Left, bottom, front corner
91  /// Returns an array of 3 floats for xsize(), ysize(), zsize() representing
92  /// the size of the bounding box.
93  const float *getSize() const; // width, height, depth.
94  /// Returns the number of voxels in x, y, z.
95  const int *getRes() const; // Raw size in voxels. w, h, d
96 
97  /// Number of channels in the texture image
98  int getNChannels() const;
99 
100  /// Query channel names
101  const char *getChannelName(int idx) const;
102 
103  /// Return the number of floats in the given channel
104  int getChannelSize(int idx) const;
105 
106  /// Find the index of a named channel. Returns -1 if not found.
107  int getChannelNumber(const char *name) const;
108 
109  /// Once a texture is open, you must open a handle to a channel to be able
110  /// to access data in the channel. Returns 0 on failure or 1 on success.
111  /// @note Only a single channel can be open per manager.
112  int openChannel(const char *channel_name);
113 
114  /// Set the evaluation filter. This filter filter can be any one of the
115  /// standard Houdini filter types. The filtering is use for evaluation and
116  /// integration of the texture. Returns 0 on failure.
117  /// @see UT_Filter.
118  int setFilter(const char *filter_name, fpreal filter_width);
119 
120  /// Evaluate the 3D texture at the given position. Returns 0 on failure.
121  /// Uses the filter set by setFilter().
122  /// @note The @c result buffer should have enough storage to hold
123  /// getChannelSize().
124  int sample(const UT_Vector3 &pos, float *result);
125 
126  /// Evaluate the gradient of the 3D texture at the given position.
127  /// Uses the filter set by setFilter().
128  /// @note The gradient can only be computed on scalar channels.
129  /// @note 3 floats will be returned for a scalar channel.
130  int gradient(const UT_Vector3 &pos, float *result);
131 
132  /// Integrate from p0 to p1 and return the integration result.
133  /// Optional controls are:
134  /// @param p0 Start of integration
135  /// @param p1 End of integration
136  /// @param result
137  /// Integration result. This should large enough to hold
138  /// getChannelSize() floats.
139  /// @param limit_max if this value of the integration exceeds
140  /// this value, then the integration will be
141  /// terminated early.
142  /// @param value_scale scale the integration value by this amount.
143  /// This scaling is applied BEFORE limit checks.
144  /// @param accuracy
145  /// A scaling on stepping. Increasing the accuracy will perform
146  /// more sub-steps on the integration, yielding a more accurate
147  /// result (at a higher cost). Increasing the accuracy can have a
148  /// significant effect on performance.
149  ///
150  /// As a result of integration, p1 will be clipped to the bounds of the
151  /// texture. As well, p0 will be moved to the point where the limit was
152  /// reached (if the limit was reached).
153  int integrate(UT_Vector3 &p0, UT_Vector3 &p1, float *result,
154  fpreal limit_max=1, fpreal value_scale=1,
155  fpreal accuracy=0);
156 
157  /// Find the intersection against the iso-surface defined by density
158  /// specified. The accuracy is how close f(p0) will be to zero.
159  /// If an intersection is found, the function will return 1.
160  /// p0 will be moved to the intersection point (or to p1 if there was no
161  /// intersection found).
162  int intersect(UT_Vector3 &p0, const UT_Vector3 &p1,
163  fpreal density, fpreal accuracy = 1e-5F);
164 
165  /// Load a channel as a flat list of floats. The data is allocated using
166  /// malloc(). It's the users responsibility for freeing this memory using
167  /// free(). Given the getRes() function returning W, H, D (width, height,
168  /// depth), the array returned will be <tt>W*H*D * getChannelSize() *
169  /// sizeof(float)</tt> bytes long.
170  /// Given an index (ix, iy, iz), the channel data can be indexed by:
171  /// <tt>ix + iy*W + iz*W*H</tt>
172  float *loadUntiledChannel();
173 
174  /// Same as loadUntitledChannel() but fills a user-allocated array.
175  int loadUntiledChannel(float *data);
176 
177 public:
178  /// This method allows the creation of a 3D texture. The bounding box
179  /// defines the are where the map is sampled.
180  ///
181  /// Compression is the level of gzip compression to use. Valid values are
182  /// between 0 (no compression) and 9 (maximum compression).
183  int createTexture(
184  const char *filename,
185  const UT_BoundingBox &box,
186  int xres,
187  int yres,
188  int zres,
189  int compression=5);
190 
191  /// Once the texture is created, please call the following code to generate
192  /// the values for the texture.
193  /// @param num_channels The number of channels
194  /// @param channel_names An array of channel names
195  /// @param channel_sizes The number of floats in each channel.
196  /// @param evaluator Callback to evaluate channel positions
197  /// @param max_samples Anti-aliasing samples
198  /// @param variance Variance threshhold for anti-aliasing to occur
199  /// @param filter_width Anti-aliasing filter width
200  /// @param jitter Amount of jitter for anti-aliasing
201  /// @note currently, only box filtering is supported for anti-aliasing
202  /// @return 0 if the process fails.
203  int fillTexture(
204  int num_channels,
205  const char *channel_names[],
206  int channel_sizes[],
207  IMG3D_TextureEval evaluator,
208  int max_samples=4,
209  fpreal variance=0.005,
210  fpreal filter_width=1,
211  fpreal jitter=1);
212 
213  /// Save flat untiled data to the file. This method perfoms the inverse
214  /// operation of loadUntiledChannel, but for multiple channels.
215  /// @param num_channels - The number of channels
216  /// @param channel_names - An array of channel names
217  /// @param channel_sizes - The number of floats in each channel
218  /// @param data - Source data for each channel
219  /// @param variance - Ignored
220  ///
221  /// Given the @c getRes() function returning W, H, D (width, height,
222  /// depth), the data array for channel i must be
223  /// <tt>W*H*D * channel_sizes[i] * sizeof(float) </tt> bytes long.
224  /// Given an index (ix, iy, iz), the channel data can be indexed by:
225  /// <tt>ix + iy*W + iz*W*H</tt>
226  ///
227  /// @return 0 if the process fails.
228  int fillUntiledTexture(
229  int num_channels,
230  const char *channel_names[],
231  int channel_sizes[],
232  const float *data[],
233  fpreal variance=0.005);
234 
235  /// @{
236  ///
237  /// It's possible store and retrieve tags (based on the read/write mode of
238  /// the file). These tags can be queried using texinfo() in VEX.
239  ///
240  bool exportTag(const char *name, int value);
241  bool exportTag(const char *name, float value);
242  bool exportTag(const char *name, const UT_Vector3 &value);
243  bool exportTag(const char *name, const UT_Vector4 &value);
244  bool exportTag(const char *name, const UT_Matrix3 &value);
245  bool exportTag(const char *name, const UT_Matrix4 &value);
246  bool exportTag(const char *name, const char *value);
247  /// @}
248 
249  /// @{
250  /// When importing, if the type doesn't match, casting will be done (where
251  /// possible). Importing a string is always possible. If the import
252  /// fails, the value will be untouched and the import will return false.
253  bool importTag(const char *name, int &value);
254  bool importTag(const char *name, float &value);
255  bool importTag(const char *name, UT_Vector3 &value);
256  bool importTag(const char *name, UT_Vector4 &value);
257  bool importTag(const char *name, UT_Matrix3 &value);
258  bool importTag(const char *name, UT_Matrix4 &value);
259  bool importTag(const char *name, UT_String &value);
260  /// @}
261 
262 public:
263  // Deprecated methods that take floating point parameters. You should
264  // use the new methods above.
265  /// @private - Please use the UT_Vector3 version
266  int SYS_DEPRECATED(8.2) sample(const float *pos, float *result)
267  { return sample(*(UT_Vector3 *)pos, result); }
268  /// @private - Please use the UT_Vector3 version
269  int SYS_DEPRECATED(8.2) gradient(const float *pos, float *result)
270  { return gradient(*(UT_Vector3 *)pos, result); }
271  /// @private - Please use the UT_Vector3 version
272  int SYS_DEPRECATED(8.2) integrate(float *p0, float *p1, float *result,
273  fpreal limit_max=1, fpreal value_scale=1,
274  fpreal accuracy=0)
275  { return integrate(*(UT_Vector3 *)p0, *(UT_Vector3 *)p1,
276  result, limit_max, value_scale, accuracy); }
277  /// @private - Please use the UT_Vector3 version
278  int SYS_DEPRECATED(8.2) intersect(float *p0, const float *p1,
279  fpreal density, fpreal accuracy = 1e-5F)
280  { return intersect(*(UT_Vector3 *)p0, *(UT_Vector3 *)p1,
281  density, accuracy); }
282  /// @private - Please use the UT_BoundingBox version
283  int SYS_DEPRECATED(8.2) createTexture(
284  const char *filename,
285  const float box[3][2],
286  int xres,
287  int yres,
288  int zres,
289  int compression=5)
290  {
291  return createTexture(filename, UT_BoundingBox(
292  box[0][0], box[1][0], box[2][0],
293  box[0][1], box[1][1], box[2][1]),
294  xres, yres, zres, compression);
295  }
296  /// @private - Please use the IMG3D_TextureEval version
297  int SYS_DEPRECATED(8.2) fillTexture(
298  int num_channels,
299  const char *channel_names[],
300  int channel_sizes[],
301  IMG3D_Manager_Eval evaluator,
302  int max_samples=4,
303  fpreal variance=0.005,
304  fpreal filter_width=1,
305  fpreal jitter=1);
306 
307 protected:
308  void *myData; // Internal data structure
309 };
310 
311 #endif
GLuint GLsizei const GLuint const GLintptr const GLsizeiptr * sizes
Definition: glcorearb.h:2620
void(* IMG3D_TextureEval)(int nvalues, const UT_Vector3 *pos, fpreal32 *result[], const char *names[], int sizes[], int for_aa)
Definition: IMG3D_Manager.h:34
#define SYS_DEPRECATED(__V__)
typedef void(APIENTRYP PFNGLCULLFACEPROC)(GLenum mode)
3D Vector class.
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)
UT_BoundingBoxT< float > UT_BoundingBox
Definition: GEO_Detail.h:43
GLboolean * data
Definition: glcorearb.h:130
GLuint const GLchar * name
Definition: glcorearb.h:785
GLsizei const GLfloat * value
Definition: glcorearb.h:823
double fpreal
Definition: SYS_Types.h:263
ScalarToVectorConverter< GridType >::Type::Ptr gradient(const GridType &grid, bool threaded, InterruptT *interrupt)
Compute the gradient of the given scalar grid.
void(* IMG3D_Manager_Eval)(int nvalues, const fpreal32 *pos, fpreal32 *result[], const char *names[], int sizes[], int for_aa)
Definition: IMG3D_Manager.h:41
#define IMG3D_API
Definition: IMG3D_API.h:10
Class to handle reading/writing 3D texture images.
Definition: IMG3D_Manager.h:68
float fpreal32
Definition: SYS_Types.h:184