HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_ComputeGPU.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: UT_ComputeGPU.h ( UT Library, C++)
7  *
8  * COMMENTS:
9  * A high level abstract interface to allow GP-GPU computing (general purpose
10  * computation on the GPU, or video card).
11  *
12  * Setting up the computation is relatively expensive, so this should only
13  * be used for large volumes of data.
14  *
15  * Once you have set up the program, output and input(s), you can change one
16  * or all of them for the next run. If you call setConstant() or setArray()
17  * with the same name as an existing constant or array, the data will be
18  * updated as long as the data format and size remains the same (otherwise
19  * another constant or texture will be created for it).
20  *
21  * You can use special macros to read from the input arrays (which are
22  * textures) using integer indices rather than floating point texture
23  * coords:
24  *
25  * IN_array_name // at current output pos.
26  * ABS_array_name (int_pos) // at an absolute position.
27  * REL_array_name (int_offset) // offset from current pos.
28  *
29  * (Note: 2D Arrays will have 2 pos / offset parms)
30  *
31  * You can use the first version to grab the corresponding input element
32  * only if it matches the output in size and dimensions (1d/2d). Otherwise,
33  * you'll get array bounds issues.
34  */
35 #ifndef UT_ComputeGPU_h
36 #define UT_ComputeGPU_h
37 
38 #include "UT_API.h"
39 
40 // Data type abtractions for OpenGL types.
42 {
43  UT_GPU_UINT1 = 0, // corresponds to GL_STENCIL_INDEX1
44  UT_GPU_UINT4, // corresponds to GL_STENCIL_INDEX4
48 
52 
54  UT_GPU_FLOAT24, // corresponds to GL_DEPTH_COMPONENT24
57 
58  // These can only be used in the context of a GLSL shader.
62 };
63 
64 class UT_String;
65 class UT_ComputeGPU;
66 
67 typedef UT_ComputeGPU *(*UT_ComputeGPUCreateFunc)();
68 
70 {
71 public:
72  virtual ~UT_ComputeGPU();
73 
75  {
76  OGL_GLSL, // OpenGL GLSL (must have OpenGL 2.0 or shader exts)
77  };
78 
79  /// Create a new UT_ComputeGPU object.
80  /// The caller takes ownership of the returned object and is responsible
81  /// for deleting it.
82  static UT_ComputeGPU *create();
83 
84  /// Register a function for creating concrete UT_ComputeGPU objects.
85  static void registerCreateFunc(UT_ComputeGPUCreateFunc create_func);
86 
87  // 0. If you're doing multiple passes, you should set how many passes you
88  // wish to do. This is optional - it defaults to 1 pass.
89  // TODO: This is not supported yet.
90  virtual void setNumPasses(int passes) = 0;
91 
92  // If enabled, your shader is using integer bit operations. Not all cards
93  // support this.
94  virtual void needBitOps(bool enable) = 0;
95  virtual bool needsBitOps() const = 0;
96 
97  // 1. Inputs to computation.
98  // You may rewrite to existing values to begin another computation.
99  // This class does not take ownership of the value array you pass in -
100  // you are responsible for deleting it, but do not do so until compute()
101  // has been called.
102  // The OpenGL texture size limits the maximum array size. 1D Arrays
103  // have a max of this size squared, 2D arrays must have both dimensions
104  // under this size (see RE_OGLRender::getMaxTextureSize()). setArray()
105  // will return NULL if these limits are exceeeded.
106 
107  // Data types available for I/O
108  // - constants are usually int32's, float32's or matrices.
109  // - input and output arrays cannot be arrays of matrices (currently)
110 
111  // Constants are usually UT_GPU_FLOAT32, UT_GPU_(U)INT32 OR
112  // UT_GPU_MATRIX[n]. They can be a small array, but GLSL will not allow
113  // you to dynamically index them (ie, [x], only [1] or using fixed range
114  // loop variables like x=1 to 10). If you need to dynamically index,
115  // use an Array. Constant arrays are very lightweight, though.
116  virtual void setConstant(const char *name,
118  int vectorsize,
119  const void *value,
120  int array_size = 1,
121  bool global_var = false) = 0;
122 
123  virtual void * setArray(const char *name,
125  int vectorsize,
126  int size,
127  const void *values) = 0;
128 
129  virtual void * setArray2D(const char *name,
131  int vectorsize,
132  int width,
133  int height,
134  const void *values) = 0; // in rows.
135 
136  // flat arrays to vectors (interleaves to 1,2,3,4, 1,2,3,4). Not all
137  // components need to be specified.
138  virtual void * setArray(const char *name,
140  int vectorsize,
141  int size,
142  const void *values1,
143  const void *values2,
144  const void *values3 = 0,
145  const void *values4 = 0) = 0;
146 
147  virtual void * setArray2D(const char *name,
149  int vectorsize,
150  int width,
151  int height,
152  const void *values1,
153  const void *values2,
154  const void *values3 = 0,
155  const void *values4 = 0) = 0;
156 
157  // 2. Output data.
158  // You can add multiple outputs, but they all must be the same size, type
159  // and vectorsize. 'dest_data' is where the results are written.
160 
161  virtual void setOutputArray(const char *name,
163  int vectorsize,
164  int size,
165  void *dest_data) = 0;
166 
167  virtual void setOutputArray2D(const char *name,
169  int vectorsize,
170  int width,
171  int height,
172  void *dest_data) = 0;
173 
174  // Convienience method to determine the size of the array you will need
175  // for an output buffer (or need to provide for an input buffer).
176  // 1D arrays only need to pass xsize.
177  virtual int getDataByteSize(UT_GPUType type, int vectorsize,
178  int xsize, int ysize = 1) = 0;
179 
180  // 3. GLSL/Cg Program (false if it fails to compile)
181  // 'name' is arbitrary, for debug messages.
182  // 'program' is the actual program code.
183  // If 'auto_generate_framework' is true, this class prepends the GLSL
184  // constant and texture declarations (as named above), then
185  // 'void main(void) {', your code, and then '}' (so all you need to do is
186  // fill in the actual code). If non-NULL, 'preamble_code' will be placed
187  // before the declarations.
188 
189  virtual void setLanguage(UT_OGLComputeLanguage lang) = 0;
190 
191  virtual bool setProgram(const char *name,
192  const char *program,
193  bool auto_generate_framework = true,
194  const char *preamble_code = 0,
195  const char *function_code = 0) = 0;
196 
197  // This allows you to define macros and symbols for preprocessing.
198  virtual void defineSymbol(const char *symbol,
199  const char *value) = 0;
200 
201  // 4. Computation
202  // Runs the program on the inputs to produce the output. Returns a
203  // pointer to the result (in the output format and dimensions specified
204  // above). Returns false if an opengl error occured.
205  // Once you have called compute, you may begin another computation
206  // before fetching the results (just go back to step 1).
207 
208  // 'async_read' starts the DMA transfer of the results after the
209  // computation is finshed. Useful when you have more than one output,
210  // or more work to do between compute() and getResult(). Note
211  // that this call will block until the computation is done, so for long
212  // computations, you may want to take the latency hit. If pixel buffer
213  // objects are not supported, this is ignored.
214 
215  virtual bool compute(UT_String &errors, bool async_read = false) = 0;
216 
217  // 5. Fetch Results
218  // Notify the engine that you'd like to use your results. With multiple
219  // active computations, this removes the oldest and another getResult()
220  // will begin fetching from the next oldest computation.
221  //
222  // Your results will be available _after_ this method is called. This
223  // returns false if your results could not be read.
224  virtual bool getResults() = 0;
225 
226  // Alternatively, you can use a deferred scheme to retrive the data.
227  // 1. Call deferred fetch to grab a key to the results.
228  // 2. You can optionally call beginDeferredRead() some time afterward
229  // to start the asynchronouse read.
230  // 3. Call endDeferredRead() to ensure that all results have been read.
231  // The key is no longer valid after step 3.
232 
233  virtual void * useDeferredFetch() = 0;
234 
235 protected:
236  UT_ComputeGPU();
237 };
238 
239 /// Class for manipulating global state needed for GPU computation.
240 /// This is a singleton class. You can access the singleton by calling
241 /// the static get() method.
243 {
244 public:
245  virtual ~UT_ComputeGPUState();
246 
247  static UT_ComputeGPUState *get();
248  static void set(UT_ComputeGPUState *gpu_state);
249 
250  virtual void initStandalone(bool one_per_thread = true) {}
251  virtual void cleanupStandalone() {}
252  virtual void getGLSLComputeDir(UT_String &dir) {}
253 
254  // Returns true if the graphics hardware has proper support to use this
255  // class.
256  virtual bool hasGPUSupport() { return false; }
257 
258  virtual bool areBitOpsSupported() { return false; }
259 
260  virtual void beginDeferredRead(void *key) {}
261  virtual bool endDeferredRead(void *key) { return false; }
262  virtual void cancelDeferredRead(void *key) {}
263 
264  // Returns true if texture rectangles must be used (because standard 2D
265  // textures do not support most higher formats on some hardware)
266  virtual bool useTextureRectangles() { return false; }
267 
268  // The largest sizes that this GPU can handle.
269  virtual int getMaxArraySize() { return 0; }
270  virtual int getMaxArraySize2D() { return 0; }
271 
272  // Clears all the GP-GPU allocated objects. You don't normally need to
273  // call this.
274  virtual void reset() {}
275 
276  virtual void restoreState() {}
277  virtual void cleanupState() {}
278 
279 protected:
281 };
282 
283 #endif
virtual bool hasGPUSupport()
virtual int getMaxArraySize()
virtual bool areBitOpsSupported()
virtual void reset()
virtual int getMaxArraySize2D()
#define UT_API
Definition: UT_API.h:13
virtual void cleanupState()
virtual void getGLSLComputeDir(UT_String &dir)
GLsizeiptr size
Definition: glcorearb.h:663
GLint GLsizei width
Definition: glcorearb.h:102
virtual void initStandalone(bool one_per_thread=true)
UT_GPUType
Definition: UT_ComputeGPU.h:41
virtual void cancelDeferredRead(void *key)
virtual void restoreState()
GLenum GLsizei GLsizei GLint * values
Definition: glcorearb.h:1601
GLuint const GLchar * name
Definition: glcorearb.h:785
virtual void cleanupStandalone()
virtual bool endDeferredRead(void *key)
GLint GLsizei GLsizei height
Definition: glcorearb.h:102
GLsizei const GLfloat * value
Definition: glcorearb.h:823
virtual void beginDeferredRead(void *key)
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
UT_ComputeGPU *(* UT_ComputeGPUCreateFunc)()
Definition: UT_ComputeGPU.h:67
virtual bool useTextureRectangles()
GLbitfield GLuint program
Definition: glcorearb.h:1930