Style Cleanup:
[blender.git] / doc / python_api / rst / gpu.rst
1 GPU functions (gpu)
2 ===================
3
4 .. module:: gpu
5
6 This module provides access to materials GLSL shaders.
7
8 *****
9 Intro
10 *****
11
12 Module to provide functions concerning the GPU implementation in Blender, in particular
13 the GLSL shaders that blender generates automatically to render materials in the 3D view
14 and in the game engine.
15
16 .. warning::
17
18     The API provided by this module should be consider unstable. The data exposed by the API 
19     are are closely related to Blender's internal GLSL code and may change if the GLSL code 
20     is modified (e.g. new uniform type). 
21
22
23 *********
24 Constants
25 *********
26
27 --------------
28 GLSL data type
29 --------------
30
31 .. _data-type:
32
33 Type of GLSL data.
34 For shader uniforms, the data type determines which glUniform function
35 variant to use to send the uniform value to the GPU.
36 For vertex attributes, the data type determines which glVertexAttrib function
37 variant to use to send the vertex attribute to the GPU.
38
39 See export_shader_
40
41 .. data:: GPU_DATA_1I
42
43    one integer
44
45    :value: 1
46
47 .. data:: GPU_DATA_1F
48
49    one float
50
51    :value: 2
52
53 .. data:: GPU_DATA_2F
54
55    two floats
56
57    :value: 3
58
59 .. data:: GPU_DATA_3F
60
61    three floats
62    
63    :value: 4
64    
65 .. data:: GPU_DATA_4F
66
67    four floats
68    
69    :value: 5
70    
71 .. data:: GPU_DATA_9F
72
73    matrix 3x3 in column-major order
74
75    :value: 6
76
77 .. data:: GPU_DATA_16F
78
79    matrix 4x4 in column-major order
80
81    :value: 7
82
83 .. data:: GPU_DATA_4UB
84
85    four unsigned byte
86
87    :value: 8
88
89 -----------------
90 GLSL uniform type
91 -----------------
92
93 .. _uniform-type:
94
95 Constants that specify the type of uniform used in a GLSL shader. 
96 The uniform type determines the data type, origin and method
97 of calculation used by Blender to compute the uniform value. 
98
99 The calculation of some of the uniforms is based on matrices available in the scene:
100
101     .. _mat4_cam_to_world:
102     .. _mat4_world_to_cam:
103
104     *mat4_cam_to_world*
105       Model matrix of the camera. OpenGL 4x4 matrix that converts 
106       camera local coordinates to world coordinates. In blender this is obtained from the
107       'matrix_world' attribute of the camera object.
108
109       Some uniform will need the *mat4_world_to_cam*
110       matrix computed as the inverse of this matrix.
111
112     .. _mat4_object_to_world:
113     .. _mat4_world_to_object:
114
115     *mat4_object_to_world*
116       Model matrix of the object that is being rendered. OpenGL 4x4 matric that converts
117       object local coordinates to world coordinates. In blender this is obtained from the
118       'matrix_world' attribute of the object.
119   
120       Some uniform will need the *mat4_world_to_object* matrix, computed as the inverse of this matrix.
121   
122     .. _mat4_lamp_to_world:
123     .. _mat4_world_to_lamp:
124
125     *mat4_lamp_to_world*
126       Model matrix of the lamp lighting the object. OpenGL 4x4 matrix that converts lamp
127       local coordinates to world coordinates. In blender this is obtained from the
128       'matrix_world' attribute of the lamp object.
129       
130       Some uniform will need the *mat4_world_to_lamp* matrix
131       computed as the inverse of this matrix.
132
133 .. data:: GPU_DYNAMIC_OBJECT_VIEWMAT
134
135     The uniform is a 4x4 GL matrix that converts world coordinates to 
136     camera coordinates (see mat4_world_to_cam_). Can be set once per frame.
137     There is at most one uniform of that type per shader.
138
139     :value: 1
140
141 .. data:: GPU_DYNAMIC_OBJECT_MAT
142
143     The uniform is a 4x4 GL matrix that converts object coordinates 
144     to world coordinates (see mat4_object_to_world_). Must be set before drawing the object.
145     There is at most one uniform of that type per shader.
146
147     :value: 2
148
149 .. data:: GPU_DYNAMIC_OBJECT_VIEWIMAT
150
151     The uniform is a 4x4 GL matrix that converts coordinates
152     in camera space to world coordinates (see mat4_cam_to_world_).
153     Can be set once per frame. 
154     There is at most one uniform of that type per shader.
155
156     :value: 3
157
158 .. data:: GPU_DYNAMIC_OBJECT_IMAT
159
160     The uniform is a 4x4 GL matrix that converts world coodinates
161     to object coordinates (see mat4_world_to_object_).
162     Must be set before drawing the object.
163     There is at most one uniform of that type per shader.
164    
165     :value: 4
166    
167 .. data:: GPU_DYNAMIC_OBJECT_COLOR
168
169     The uniform is a vector of 4 float representing a RGB color + alpha defined at object level.
170     Each values between 0.0 and 1.0. In blender it corresponds to the 'color' attribute of the object.
171     Must be set before drawing the object.
172     There is at most one uniform of that type per shader.
173    
174     :value: 5
175    
176 .. data:: GPU_DYNAMIC_LAMP_DYNVEC
177
178     The uniform is a vector of 3 float representing the direction of light in camera space.
179     In Blender, this is computed by 
180
181     mat4_world_to_cam_ * (-vec3_lamp_Z_axis) 
182
183     as the lamp Z axis points to the opposite direction of light.
184     The norm of the vector should be unity. Can be set once per frame.
185     There is one uniform of that type per lamp lighting the material.
186
187     :value: 6
188    
189 .. data:: GPU_DYNAMIC_LAMP_DYNCO
190
191     The uniform is a vector of 3 float representing the position of the light in camera space.
192     Computed as 
193     
194     mat4_world_to_cam_ * vec3_lamp_pos
195
196     Can be set once per frame.
197     There is one uniform of that type per lamp lighting the material.
198    
199     :value: 7
200    
201 .. data:: GPU_DYNAMIC_LAMP_DYNIMAT
202
203     The uniform is a 4x4 GL matrix that converts vector in camera space to lamp space.
204     Computed as 
205
206     mat4_world_to_lamp_ * mat4_cam_to_world_
207
208     Can be set once per frame.
209     There is one uniform of that type per lamp lighting the material.
210
211     :value: 8
212
213 .. data:: GPU_DYNAMIC_LAMP_DYNPERSMAT
214
215     The uniform is a 4x4 GL matrix that converts a vector in camera space to shadow buffer depth space.
216     Computed as 
217
218     mat4_perspective_to_depth_ * mat4_lamp_to_perspective_ * mat4_world_to_lamp_ * mat4_cam_to_world_.
219
220     .. _mat4_perspective_to_depth:
221
222     *mat4_perspective_to_depth* is a fixed matrix defined as follow::
223
224         0.5 0.0 0.0 0.5
225         0.0 0.5 0.0 0.5
226         0.0 0.0 0.5 0.5
227         0.0 0.0 0.0 1.0
228
229     This uniform can be set once per frame. There is one uniform of that type per lamp casting shadow in the scene.
230
231     :value: 9
232
233 .. data:: GPU_DYNAMIC_LAMP_DYNENERGY
234
235     The uniform is a single float representing the lamp energy. In blender it corresponds
236     to the 'energy' attribute of the lamp data block.
237     There is one uniform of that type per lamp lighting the material.
238
239     :value: 10
240
241 .. data:: GPU_DYNAMIC_LAMP_DYNCOL
242
243     The uniform is a vector of 3 float representing the lamp color. 
244     Color elements are between 0.0 and 1.0. In blender it corresponds
245     to the 'color' attribute of the lamp data block.
246     There is one uniform of that type per lamp lighting the material.
247
248     :value: 11
249
250 .. data:: GPU_DYNAMIC_SAMPLER_2DBUFFER
251
252     The uniform is an integer representing an internal texture used for certain effect
253     (color band, etc). 
254         
255     :value: 12
256
257 .. data:: GPU_DYNAMIC_SAMPLER_2DIMAGE
258
259     The uniform is an integer representing a texture loaded from an image file. 
260
261     :value: 13
262
263 .. data:: GPU_DYNAMIC_SAMPLER_2DSHADOW
264
265     The uniform is an integer representing a shadow buffer corresponding to a lamp
266     casting shadow.
267
268     :value: 14
269
270 -------------------
271 GLSL attribute type
272 -------------------
273
274 .. _attribute-type:
275
276 Type of the vertex attribute used in the GLSL shader. Determines the mesh custom data
277 layer that contains the vertex attribute. 
278
279 .. data:: CD_MTFACE
280
281     Vertex attribute is a UV Map. Data type is vector of 2 float.
282
283     There can be more than one attribute of that type, they are differenciated by name.
284     In blender, you can retrieve the attribute data with:
285
286     .. code-block:: python
287
288         mesh.uv_textures[attribute['name']]
289
290     :value: 5
291
292 .. data:: CD_MCOL
293
294     Vertex attribute is color layer. Data type is vector 4 unsigned byte (RGBA).
295
296     There can be more than one attribute of that type, they are differenciated by name.
297     In blender you can retrieve the attribute data with:
298
299     .. code-block:: python
300
301         mesh.vertex_colors[attribute['name']]
302
303     :value: 6
304
305 .. data:: CD_ORCO
306
307     Vertex attribute is original coordinates. Data type is vector 3 float.
308
309     There can be only 1 attribute of that type per shader.      
310     In blender you can retrieve the attribute data with:
311   
312     .. code-block:: python
313
314         mesh.vertices
315
316     :value: 14
317
318 .. data:: CD_TANGENT
319
320     Vertex attribute is the tangent vector. Data type is vector 4 float.
321
322     There can be only 1 attribute of that type per shader.
323     There is currently no way to retrieve this attribute data via the RNA API but a standalone 
324     C function to compute the tangent layer from the other layers can be obtained from
325     blender.org.
326
327     :value: 18
328
329 *********
330 Functions
331 *********
332
333 .. _export_shader:
334
335 .. function:: export_shader(scene,material)
336
337     Extracts the GLSL shader producing the visual effect of material in scene for the purpose of 
338     reusing the shader in an external engine. This function is meant to be used in material exporter 
339     so that the GLSL shader can be exported entirely. The return value is a dictionary containing the
340     shader source code and all associated data. 
341
342     :arg scene: the scene in which the material in rendered.
343     :type scene: :class:`bpy.types.Scene`
344     :arg material: the material that you want to export the GLSL shader
345     :type material: :class:`bpy.types.Material`
346     :return: the shader source code and all associated data in a dictionary
347     :rtype: dictionary
348
349     The dictionary contains the following elements:
350
351     * ['fragment'] : string
352         fragment shader source code.
353     
354     * ['vertex'] : string
355         vertex shader source code.
356
357     * ['uniforms'] : sequence
358         list of uniforms used in fragment shader, can be empty list. Each element of the
359         sequence is a dictionary with the following elements:
360
361         * ['varname'] : string
362             name of the uniform in the fragment shader. Always of the form 'unf<number>'.
363
364         * ['datatype'] : integer
365             data type of the uniform variable. Can be one of the following:
366
367             * :data:`gpu.GPU_DATA_1I` : use glUniform1i
368             * :data:`gpu.GPU_DATA_1F` : use glUniform1fv
369             * :data:`gpu.GPU_DATA_2F` : use glUniform2fv
370             * :data:`gpu.GPU_DATA_3F` : use glUniform3fv
371             * :data:`gpu.GPU_DATA_4F` : use glUniform4fv
372             * :data:`gpu.GPU_DATA_9F` : use glUniformMatrix3fv
373             * :data:`gpu.GPU_DATA_16F` : use glUniformMatrix4fv
374
375         * ['type'] : integer
376             type of uniform, determines the origin and method of calculation. See uniform-type_.
377             Depending on the type, more elements will be be present.
378
379         * ['lamp'] : :class:`bpy.types.Object`
380             Reference to the lamp object from which the uniforms value are extracted. Set for the following uniforms types:
381
382             .. hlist::
383                :columns: 3
384
385                * :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`
386                * :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`
387                * :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT`
388                * :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
389                * :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY`
390                * :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL`
391                * :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`
392
393             Notes:
394
395             * The uniforms :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`, :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`, :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT` and :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
396               refer to the lamp object position and orientation, both of can be derived from the object world matrix:
397
398               .. code-block:: python
399
400                 obmat = uniform['lamp'].matrix_world
401
402               where obmat is the mat4_lamp_to_world_ matrix of the lamp as a 2 dimensional array,
403               the lamp world location location is in obmat[3].
404
405             * The uniform types :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY` and :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL` refer to the lamp data bloc that you get from:
406
407               .. code-block:: python
408
409                 la = uniform['lamp'].data
410           
411               from which you get la.energy and la.color
412
413             * Lamp duplication is not supported: if you have duplicated lamps in your scene
414               (i.e. lamp that are instantiated by dupligroup, etc), this element will only 
415               give you a reference to the orignal lamp and you will not know which instance
416               of the lamp it is refering too. You can still handle that case in the exporter
417               by distributing the uniforms amongst the duplicated lamps.
418               
419         * ['image'] : :class:`bpy.types.Image`
420             Reference to the image databloc. Set for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE`. You can get the image data from:
421
422             .. code-block:: python
423
424                # full path to image file
425                uniform['image'].filepath
426                # image size as a 2-dimensional array of int
427                uniform['image'].size
428
429         * ['texnumber'] : integer
430             Channel number to which the texture is bound when drawing the object.
431             Set for uniform types :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`, :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE` and :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`.
432
433             This is provided for information only: when reusing the shader outside blencer, 
434             you are free to assign the textures to the channel of your choice and to pass
435             that number channel to the GPU in the uniform.
436
437         * ['texpixels'] : byte array
438             texture data for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`. Although
439             the corresponding uniform is a 2D sampler, the texture is always a 1D texture
440             of n x 1 pixel. The texture size n is provided in ['texsize'] element. 
441             These texture are only used for computer generated texture (colorband, etc).
442             The texture data is provided so that you can make a real image out of it in the
443             exporter.
444                 
445         * ['texsize'] : integer
446             horizontal size of texture for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`. 
447             The texture data is in ['texpixels'].
448
449     * ['attributes'] : sequence
450         list of attributes used in vertex shader, can be empty. Blender doesn't use
451         standard attributes except for vertex position and normal. All other vertex
452         attributes must be passed using the generic glVertexAttrib functions.
453         The attribute data can be found in the derived mesh custom data using RNA.
454         Each element of the sequence is a dictionary containing the following elements:
455
456         * ['varname'] : string
457             name of the uniform in the vertex shader. Always of the form 'att<number>'.
458
459         * ['datatype'] : integer
460             data type of vertex attribute, can be one of the following:
461
462             * :data:`gpu.GPU_DATA_2F` : use glVertexAttrib2fv
463             * :data:`gpu.GPU_DATA_3F` : use glVertexAttrib3fv
464             * :data:`gpu.GPU_DATA_4F` : use glVertexAttrib4fv
465             * :data:`gpu.GPU_DATA_4UB` : use glVertexAttrib4ubv
466
467         * ['number'] : integer
468             generic attribute number. This is provided for information only. Blender 
469             doesn't use glBindAttribLocation to place generic attributes at specific location,
470             it lets the shader compiler place the attributes automatically and query the 
471             placement with glGetAttribLocation. The result of this placement is returned in 
472             this element. 
473
474             When using this shader in a render engine, you should either use
475             glBindAttribLocation to force the attribute at this location or use 
476             glGetAttribLocation to get the placement chosen by the compiler of your GPU.
477
478         * ['type'] : integer
479             type of the mesh custom data from which the vertex attribute is loaded. 
480             See attribute-type_.
481
482         * ['name'] : string or integer
483             custom data layer name, used for attribute type :data:`gpu.CD_MTFACE` and :data:`gpu.CD_MCOL`.
484
485     Example:
486
487     .. code-block:: python
488
489         import gpu
490         # get GLSL shader of material Mat.001 in scene Scene.001
491         scene = bpy.data.scenes['Scene.001']
492         material = bpy.data.materials['Mat.001']
493         shader = gpu.export_shader(scene,material)
494         # scan the uniform list and find the images used in the shader
495         for uniform in shader['uniforms']:
496             if uniform['type'] == gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE:
497                 print("uniform {0} is using image {1}".format(uniform['varname'], uniform['image'].filepath))
498         # scan the attribute list and find the UV Map used in the shader
499         for attribute in shader['attributes']:
500             if attribute['type'] == gpu.CD_MTFACE:
501                 print("attribute {0} is using UV Map {1}".format(attribute['varname'], attribute['name']))
502
503 *****
504 Notes
505 *****
506
507 .. _mat4_lamp_to_perspective:
508
509 1. Calculation of the *mat4_lamp_to_perspective* matrix for a spot lamp.
510
511    The following pseudo code shows how the *mat4_lamp_to_perspective* matrix is computed 
512    in blender for uniforms of :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` type::
513
514      #Get the lamp datablock with:
515      lamp=bpy.data.objects[uniform['lamp']].data
516
517      #Compute the projection matrix:
518      #  You will need these lamp attributes:
519      #  lamp.clipsta : near clip plane in world unit
520      #  lamp.clipend : far clip plane in world unit
521      #  lamp.spotsize : angle in degree of the spot light
522
523      #The size of the projection plane is computed with the usual formula:
524      wsize = lamp.clista * tan(lamp.spotsize/2)
525
526      #And the projection matrix:
527      mat4_lamp_to_perspective = glFrustum(-wsize,wsize,-wsize,wsize,lamp.clista,lamp.clipend)
528
529 2. Creation of the shadow map for a spot lamp.
530
531    The shadow map is the depth buffer of a render performed by placing the camera at the
532    spot light position. The size of the shadow map is given by the attribute lamp.bufsize : 
533    shadow map size in pixel, same size in both dimensions.