DI-Guy C++ SDK Reference  13.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
diguyGraphicsShaderProgram.h
Go to the documentation of this file.
1 
2 /*********************************************************************
3  ** Copyright (c) 1992-2014 VT MAK
4  ** All rights reserved.
5  *********************************************************************/
6 
7 /*********************************************************************/
14 #ifndef __diguyGraphicsShaderProgram_H
15 #define __diguyGraphicsShaderProgram_H
16 
17 
18 #ifdef SWIG
19 %module diguyGraphicsShaderInstance
20 #else
21 #define CPLUSPLUS_ONLY
22 #endif
23 
24 #ifdef CPLUSPLUS_ONLY
25 #include <diguy_constants.h>
26 #include <declspec_diguy.h>
27 
28 class diguyGraphicsLink;
29 class diguyGraphicsShaderProgram;
30 class diguyGraphicsShaderInstance;
31 class bdiShaderProgram;
32 
33 /****************************************************************************/
34 
35 #endif
36 
37 
38 /****************************************************************************/
39 /*l
40  *b Description:
41  **
42  ** This enumeration lists the quality level of various shader programs
43  ** that DI-Guy might create.
44  **
45  ** int diguyApp::set_max_character_shader_quality_level(int quality_level);
46  ** int diguyApp::set_max_scene_object_shader_quality_level(int quality_level);
47  */
48 typedef enum
49 {
50  DIGUY_GRAPHICS_SHADER_QUALITY_UNKNOWN = -1,
51  DIGUY_GRAPHICS_SHADER_QUALITY_UNLIT = 0,
52  DIGUY_GRAPHICS_SHADER_QUALITY_PER_VERTEX = 1,
53  DIGUY_GRAPHICS_SHADER_QUALITY_PER_PIXEL = 2,
54  DIGUY_GRAPHICS_SHADER_QUALITY_PER_PIXEL_BUMP_MAPPED = 3,
55  DIGUY_GRAPHICS_SHADER_QUALITY_MAX
56 } diguyGraphicsShaderQualityLevel;
57 
58 
59 /****************************************************************************/
60 /*l
61  *b Description:
62  **
63  ** This enumeration lists the types of shader programs that DI-Guy
64  ** might request.
65  **
66  *i DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_GENERAL
67  **
68  *i DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_SKIN
69  **
70  *i DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_REFLECTOR
71  **
72  */
73 typedef enum
74 {
75  DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_UNKNOWN = -1,
76  DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_GENERAL = 0,
77  DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_SKIN,
78  DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_REFLECTOR
79 
80 } diguyGraphicsShaderProgramType;
81 
82 
83 /****************************************************************************/
99 class BDI_DECLSPEC_diguy diguyGraphicsShaderProgram
100 {
101 
102 public:
103 
104 /*****************************************************************************/
117  /*l
118  *b Returns:
119  **
120  ** name of the shader This pointer will never be NULL.
121  */
122  const char* get_name();
123 
124  /*l
125  *b Returns:
126  **
127  ** the vertex filename of the shader This pointer will never be NULL.
128  */
129  const char* get_vertex_shader_filename();
130 
131  /*l
132  *b Returns:
133  **
134  ** the pixel shader filename of the shader This pointer will never be NULL.
135  */
136  const char* get_pixel_shader_filename();
137 
138  /*l
139  *b Returns:
140  **
141  ** program type of the shader; see diguyGraphicsShaderProgramType
142  */
143  diguyGraphicsShaderProgramType get_shader_type();
144 
145  /*l
146  *b Returns:
147  **
148  ** shader version
149  */
150  const char* get_shader_version();
151 
152  /*l
153  *b Returns:
154  **
155  ** the quality level type of the shader; see
156  ** diguyGraphicsShaderQualityLevel
157  */
158  diguyGraphicsShaderQualityLevel get_quality_level();
159 
160  /*l
161  *b Description:
162  **
163  ** This function derives filenames for shader programs from the
164  ** provided information.
165  **
166  *b Arguments:
167  **
168  *a result - string buffer in which result should be placed
169  *a result_max_len - size of supplied string buffer; too small will
170  *a result in a truncated filename
171  *a shader_base_name - base name of shader program; e.g. "diguy_character"
172  *a shader_language - language of shader program; e.g. "glsl" or
173  *a "hlsl"
174  *a shader_type - shader program type; e.g. "vert" or "frag"
175  *a include_diguy_default_shader_directory - pass 1 to include the
176  *a default DI-Guy shader directory in the filename;
177  *a pass 0 to return the filename only with no path
178  **
179  ** The constructed filename has the format
180  ** "(shader_base_name)_(shader_language).(shader_type)"; e.g.,
181  ** "diguy_character_glsl.vert".
182  **
183  ** The DI-Guy shader directory defaults to $DIGUY/geometry/shaders.
184  **
185  *b Returns:
186  **
187  ** filename result in the result argument
188  */
189  void derive_diguy_shader_source_filename(char* result,
190  int result_max_len,
191  const char* shader_base_name,
192  const char* shader_language,
193  const char* shader_type,
194  int include_diguy_default_shader_directory);
195 
196  /*l
197  *b Description:
198  **
199  ** Prints information about the shader to the log.
200  */
201  void print_shader_info_to_log();
202 
203 
204  /*l
205  *b Description:
206  **
207  ** Forces the underlying shader to load. Returns 0 on sucess.
208  */
209  int load();
210 
211 /*****************************************************************************/
216  /*l
217  *b Description:
218  **
219  ** Sets a bit mask consisting of diguyTextureMapMasks or'd together
220  ** to specify what textures should bind when this shader is active.
221  **
222  ** See %DIGUY%\programming_examples\diguy_graphics_api\ogl_examples\common\diguyOglGraphicsShaderProgram.cpp
223  ** for an example of usage. By default in the graphics API we attempt
224  ** to bind all textures.
225  */
226  int set_textures_used_bitmask(int texture_bitmask);
227 
228  /*l
229  *b Returns:
230  **
231  ** the current or'd together list of diguyTextureMapMasks that this
232  ** shader attempts to bind. Defaults to
233  ** DIGUY_TEXTURES_MAP_MASK_ALL (0xffffffff)
234  */
235  int get_textures_used_bitmask();
236 
237 
238 /*****************************************************************************/
250 #ifdef CPLUSPLUS_ONLY
251 
252  /*l
253  *b Description:
254  **
255  ** This function will be called by DI-Guy when it is time for the
256  ** vertex part of this shader to be loaded and compiled. The utility
257  ** function derive_diguy_shader_source_filename() can be used to
258  ** convert the passed filename_base to an actual filename.
259  **
260  ** For example, assume that m_vertex_shader_filename is a character
261  ** array of 512 bytes. The following function call would derive an
262  ** appropriate vertex shader filename:
263  **
264  *e derive_diguy_shader_source_filename(m_vertex_shader_filename,
265  *e 511,
266  *e filename_base,
267  *e "glsl",
268  *e "vert",
269  *e 1);
270  **
271  ** This function is called during the Build Stage.
272  **
273  *b Returns:
274  **
275  ** 0 to indicate load was successful, -1 otherwise
276  **
277  *i Immediate Mode:
278  **
279  ** Immediate mode renderers usually do override this function.
280  **
281  *i Scene Graph:
282  **
283  ** Scene graph renderers usually do override this function.
284  **
285  *b Callable From:
286  **
287  *- - N/A (automatically called by DI-Guy Graphics API during
288  *- the Build Stage)
289  */
290  virtual int load_vertex_shader_source(const char* filename_base);
291 
292  /*l
293  *b Description:
294  **
295  ** This function is the pixel shader (AKA fragment shader in OpenGL)
296  ** equivalent of load_vertex_shader_source().
297  */
298  virtual int load_pixel_shader_source(const char* filename_base);
299 
300  /*l
301  *b Description:
302  **
303  ** This function will be called by DI-Guy if this shader program
304  ** should be reloaded. The same filenames derived in the
305  ** load_vertex_shader_source() and load_pixel_shader_source()
306  ** functions should be used.
307  **
308  ** This function can be called during the Update Stage.
309  **
310  *b Returns:
311  **
312  ** 0 to indicate reload was successful, -1 otherwise
313  **
314  *i Immediate Mode:
315  **
316  ** Immediate mode renderers usually do override this function.
317  **
318  *i Scene Graph:
319  **
320  ** Scene graph renderers usually do override this function.
321  **
322  *b Callable From:
323  **
324  *- - N/A (automatically called by DI-Guy Graphics API during
325  *- the Build Stage)
326  */
327  virtual int reload();
328 
329  /*l
330  *b Description:
331  **
332  ** This function will be called by DI-Guy when it is time for the
333  ** shader program to be linked.
334  **
335  ** This function is called during the Build Stage after the
336  ** load_vertex_shader_source() and load_pixel_shader_source()
337  ** functions.
338  **
339  ** Once the link has successfully completed shader variable bind
340  ** indices can be looked up.
341  **
342  *b Returns:
343  **
344  ** 0 to indicate link was successful, -1 otherwise
345  **
346  *i Immediate Mode:
347  **
348  ** Immediate mode renderers usually do override this function.
349  **
350  *i Scene Graph:
351  **
352  ** Scene graph renderers can override this function.
353  **
354  *b Callable From:
355  **
356  *- - N/A (automatically called by DI-Guy Graphics API during
357  *- the Build Stage)
358  */
359  virtual int link();
360 
361  /*l
362  *b Description:
363  **
364  ** Returns whether the shader has been loaded. Note that because a
365  ** shader has been loaded doesn't mean that it is valid. See
366  ** get_valid().
367  **
368  *b Returns:
369  **
370  ** 1 if shader has been loaded; 0 if not
371  */
372  virtual int get_loaded();
373 
374  /*l
375  *b Description:
376  **
377  ** Returns whether the shader has been linked. Note that this only
378  ** means that it is been attempted to link the shader. The link may
379  ** have failed, and the shader not be valid. See get_valid().
380  **
381  *b Returns:
382  **
383  ** 1 if shader has been linked; 0 if not
384  */
385  virtual int get_linked();
386 
387  /*l
388  *b Description:
389  **
390  ** Returns whether shader is valid. An invalid shader will not work
391  ** correctly, leaving graphics that use this shader unshaded. What
392  ** this will look like visually in undetermined.
393  **
394  *b Returns:
395  **
396  ** 1 if shader is valid; 0 if not
397  */
398  virtual int get_valid();
399 
400  /*l
401  *b Description:
402  **
403  ** This function will be called by DI-Guy when this program is being
404  ** bound for rendering.
405  **
406  ** It is during this function call that program level shader
407  ** variables should be set. Program level variables will affect
408  ** *all* shader operations in which this program is active.
409  ** Variables that should affect specific instances of a shader should
410  ** be set in diguyGraphicsShaderInstance::bind().
411  **
412  ** One example in the DI-Guy reference shaders is the
413  ** ufrm_textures_enabled variable. Setting it to 0 will prevent
414  ** textures from being applied during the shader program run.
415  **
416  ** This happens during the Draw Stage.
417  **
418  *i Immediate Mode:
419  **
420  ** Immediate mode renderers can override this function.
421  **
422  *i Scene Graph:
423  **
424  ** Scene graph renderers usually do not override this function; the
425  ** renderer will typically do this internally. If shader variables
426  ** need to be bound, however, this function should be overridden.
427  **
428  *b Callable From:
429  **
430  *- - N/A (automatically called by DI-Guy Graphics API during
431  *- the Draw Stage)
432  */
433  virtual int bind();
434 
435  /*l
436  *b Description:
437  **
438  ** In general variables that were set in bind() should be unset or
439  ** unbound here.
440  **
441  ** This happens during the Draw Stage.
442  **
443  *i Immediate Mode:
444  **
445  ** Immediate mode renderers can override this function.
446  **
447  *i Scene Graph:
448  **
449  ** Scene graph renderers usually do not override this function; the
450  ** renderer will typically do this internally. If the bind()
451  ** function was overridden, however, this function probably should
452  ** be, too.
453  **
454  *b Callable From:
455  **
456  *- - N/A (automatically called by DI-Guy Graphics API during
457  *- the Draw Stage)
458  */
459  virtual int unbind();
460 
461 
462  /*l
463  *b Description:
464  **
465  ** This function will be called by DI-Guy when the matrix data of
466  ** a character's links needs to be sent to the graphics card.
467  **
468  ** For GLSL-based shaders, these values are typically passed into
469  ** the vertex shader via uniform variables.
470  **
471  ** Note that the format of the data in mat_data will be affected by
472  ** the bdiGraphicsInitGraphicsAPI variable
473  ** transpose_shader_matrices value.
474  **
475  *i Immediate Mode:
476  **
477  ** Immediate mode renderers usually do override this function.
478  **
479  *i Scene Graph:
480  **
481  ** Scene graph renderers usually do not override this function,
482  ** but instead use diguyGraphicsShape::get_shader_matrix_data() during the Update Stage.
483  **
484  *b Callable From:
485  **
486  *- - N/A (automatically called by DI-Guy Graphics API during
487  *- the Draw Stage)
488  */
489  virtual int bind_link_matrices(int num_matrices,
490  const float* mat_data);
491 
492  /*l
493  *b Description:
494  **
495  ** This function will be called by DI-Guy when the color data of
496  ** a character's links needs to be sent to the graphics card.
497  **
498  ** For GLSL-based shaders, these values are typically passed into
499  ** the vertex shader via uniform variables.
500  **
501  *b Callable From:
502  **
503  *- - N/A (automatically called by DI-Guy Graphics API during
504  *- the Draw Stage)
505  */
506  virtual int bind_color_array(int num_colors,
507  const float* color_data);
508 
509  /*l
510  *b Description:
511  **
512  ** These functions will be called by DI-Guy when there is a shader
513  ** uniform that needs to be updated and sent to the graphics card.
514  **
515  ** For GLSL-based shaders, these values are typically passed into the
516  ** shader via uniform variables. This function will get repeatedly
517  ** invoked if a character is using per shape materials. See
518  ** diguyGraphicsShape::set_material_parameter_4f() for more
519  ** details.
520  **
521  *b Callable From:
522  **
523  *- - N/A (automatically called by DI-Guy Graphics API during
524  *- the Draw Stage)
525  **
526  *b Arguments:
527  **
528  *a location - the shader uniform to feed this data to, this is the
529  *a value that was retrieved via a call to get_ufrm_bind_location()
530  *a name - string representation of the uniform, useful for debugging
531  *a value_size - number of ints or floats to send to the video card
532  *a values - pointer to ints or floats to send to the video card
533  */
534  virtual int bind_uniform_with_location(int location,
535  const char* name,
536  int value_size,
537  float* values);
538 
539  virtual int bind_uniform_with_location(int location,
540  const char* name,
541  int value_size,
542  int* values);
543 
544 
545  /*l
546  *b Description:
547  **
548  ** This function will be called by DI-Guy when core code is attempting
549  ** to identify the capabilities of the end users shader. Currently
550  ** attribute locations are unused. Return -1 to disable any
551  ** functionality.
552  **
553  */
554  virtual int get_attrib_bind_location(const char* name);
555 
556  /*l
557  *b Description:
558  **
559  ** This function will be called by DI-Guy when core code is attempting
560  ** to identify the capabilities of the end users shader. This needs
561  ** to be implemented to enable per shape advanced materials. Return
562  ** -1 to disable any functionality.
563  **
564  */
565  virtual int get_uniform_bind_location(const char* name);
566 
567 #endif
568 
569 
570 /*****************************************************************************/
579  int get_num_additional_feature_names();
580 
582  const char * get_additional_feature_name(int index);
583 
585  int has_additional_feature(const char * name);
586 
587 /*****************************************************************************/
592  /*l
593  *b Returns:
594  **
595  ** The value specified in bdiGraphicsInitGraphicsAPI.transpose_shader_matrices.
596  ** Indicates if DI-Guy will attempt to transpose 4x4 matrices before sending to
597  ** video card.
598  */
599  static int get_transposed_matrix_data();
600 
601  /*l
602  *b Returns:
603  **
604  ** The value specified in bdiGraphicsInitGraphicsAPI.use_4x3_shader_matrices.
605  ** Indicates if DI-Guy is sending 4x3 matrix data instead of 4x4 data.
606  */
607  static int get_use_4x3_shader_matrix_data();
608 
609 /*****************************************************************************/
626  int get_num_variables();
627  const char* get_variable_name_at_index(int index);
628  int has_variable(const char* name);
629  const char* get_variable_type(const char* name);
630 
631  int set_variable_float(const char* name, float value, int set_current = 1, int set_initial = 0);
632  int set_variable_vec2(const char* name, float x, float y, int set_current = 1, int set_initial = 0);
633  int set_variable_vec3(const char* name, float x, float y, float z, int set_current = 1, int set_initial = 0);
634  int set_variable_vec4(const char* name, float x, float y, float z, float w, int set_current = 1, int set_initial = 0);
635  int set_variable_int(const char* name, int value, int set_current = 1, int set_initial = 0);
636 
637  int get_variable_float(const char* name, float* value, int get_current = 1);
638  int get_variable_vec2(const char* name, float* x, float* y, int get_current = 1);
639  int get_variable_vec3(const char* name, float* x, float* y, float* z, int get_current = 1);
640  int get_variable_vec4(const char* name, float* r, float* g, float* b, float* a, int get_current = 1);
641  int get_variable_int(const char* name, int* value, int get_current = 1);
642 
643 
644 /****************************************************************************/
645 /****************************************************************************/
646 /****************************************************************************/
653 /****************************************************************************/
654 /****************************************************************************/
655 /****************************************************************************/
656 
657 /****************************************************************************/
658 /****************************************************************************/
659 
665 #ifdef CPLUSPLUS_ONLY
666 
667  bdiShaderProgram* get_internal_data() {return m_internal_data;}
668 
669 protected:
670 
671  /*l
672  ** A protected constructor. Constructors are called automatically
673  ** by DI-Guy.
674  */
675  diguyGraphicsShaderProgram(void* internal_data);
676 
677  /*l
678  ** A protected destructor. Destructors are called automatically
679  ** by DI-Guy.
680  */
681  virtual ~diguyGraphicsShaderProgram();
682 
683 private:
684 
685  /*l
686  ** A pointer to internal data.
687  */
688  bdiShaderProgram* m_internal_data;
689 
690  friend class bdiShaderProgram;
691  friend class bdiGeometryFactory;
692 #endif
693 };
694 
695 
696 #endif /* __diguyGraphicsShaderProgram_H */
697