Doc: update Python 'gpu' module reference
[blender.git] / doc / python_api / rst / gpu.rst
1 *******************
2 GPU functions (gpu)
3 *******************
4
5 .. module:: gpu
6
7 This module provides access to materials GLSL shaders.
8
9
10 Intro
11 =====
12
13 Module to provide functions concerning the GPU implementation in Blender, in particular
14 the GLSL shaders that blender generates automatically to render materials in the 3D view
15 and in the game engine.
16
17 .. warning::
18
19    The API provided by this module is subject to change.
20    The data exposed by the API are are closely related to Blender's internal GLSL code
21    and may change if the GLSL code is modified (e.g. new uniform type).
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 .. data:: GPU_DATA_1F
46
47    one float
48
49 .. data:: GPU_DATA_2F
50
51    two floats
52
53 .. data:: GPU_DATA_3F
54
55    three floats
56
57 .. data:: GPU_DATA_4F
58
59    four floats
60
61 .. data:: GPU_DATA_9F
62
63    matrix 3x3 in column-major order
64
65 .. data:: GPU_DATA_16F
66
67    matrix 4x4 in column-major order
68
69 .. data:: GPU_DATA_4UB
70
71    four unsigned byte
72
73
74 GLSL Uniform Types
75 ------------------
76
77 .. _uniform-type:
78
79 Constants that specify the type of uniform used in a GLSL shader.
80 The uniform type determines the data type, origin and method
81 of calculation used by Blender to compute the uniform value.
82
83 The calculation of some of the uniforms is based on matrices available in the scene:
84
85    .. _mat4_cam_to_world:
86    .. _mat4_world_to_cam:
87
88    ``mat4_cam_to_world``
89      Model matrix of the camera. OpenGL 4x4 matrix that converts
90      camera local coordinates to world coordinates. In blender this is obtained from the
91      'matrix_world' attribute of the camera object.
92
93      Some uniform will need the *mat4_world_to_cam*
94      matrix computed as the inverse of this matrix.
95
96    .. _mat4_object_to_world:
97    .. _mat4_world_to_object:
98
99    ``mat4_object_to_world``
100      Model matrix of the object that is being rendered. OpenGL 4x4 matric that converts
101      object local coordinates to world coordinates. In blender this is obtained from the
102      'matrix_world' attribute of the object.
103
104      Some uniform will need the *mat4_world_to_object* matrix, computed as the inverse of this matrix.
105
106    .. _mat4_lamp_to_world:
107    .. _mat4_world_to_lamp:
108
109    ``mat4_lamp_to_world``
110      Model matrix of the lamp lighting the object. OpenGL 4x4 matrix that converts lamp
111      local coordinates to world coordinates. In blender this is obtained from the
112      'matrix_world' attribute of the lamp object.
113
114      Some uniform will need the *mat4_world_to_lamp* matrix
115      computed as the inverse of this matrix.
116
117
118 .. note::
119
120    Any uniforms used for view projections or transformations (object, lamp matrices for eg),
121    can only be set once per frame.
122
123
124 GLSL Object Uniforms
125 ^^^^^^^^^^^^^^^^^^^^
126
127 .. note::
128
129    - Object transformations and color must be set before drawing the object.
130    - There is at most one uniform of these types per shader.
131
132 .. data:: GPU_DYNAMIC_OBJECT_VIEWMAT
133
134    A matrix that converts world coordinates to camera coordinates (see mat4_world_to_cam_).
135
136    :type: matrix4x4
137
138 .. data:: GPU_DYNAMIC_OBJECT_MAT
139
140    A matrix that converts object coordinates to world coordinates (see mat4_object_to_world_).
141
142    :type: matrix4x4
143
144 .. data:: GPU_DYNAMIC_OBJECT_VIEWIMAT
145
146    The uniform is a 4x4 GL matrix that converts coordinates
147    in camera space to world coordinates (see mat4_cam_to_world_).
148
149    :type: matrix4x4
150
151 .. data:: GPU_DYNAMIC_OBJECT_IMAT
152
153    The uniform is a 4x4 GL matrix that converts world coodinates
154    to object coordinates (see mat4_world_to_object_).
155
156    :type: matrix4x4
157
158 .. data:: GPU_DYNAMIC_OBJECT_COLOR
159
160    An RGB color + alpha defined at object level.
161    Each values between 0.0 and 1.0.
162
163    See :class:`bpy.types.Object.color`.
164
165    :type: float4
166
167 .. data:: GPU_DYNAMIC_OBJECT_AUTOBUMPSCALE
168
169    Multiplier for bump-map scaling.
170
171    :type: float
172
173
174 GLSL Lamp Uniforms
175 ^^^^^^^^^^^^^^^^^^
176
177 .. note::
178
179    There is one uniform of that type per lamp lighting the material.
180
181 .. data:: GPU_DYNAMIC_LAMP_DYNVEC
182
183    Represents the direction of light in camera space.
184
185    Computed as:
186       mat4_world_to_cam_ * (-vec3_lamp_Z_axis)
187
188    .. note::
189       - The lamp Z axis points to the opposite direction of light.
190       - The norm of the vector should be unit length.
191
192    :type: float3
193
194 .. data:: GPU_DYNAMIC_LAMP_DYNCO
195
196    Represents the position of the light in camera space.
197
198    Computed as:
199       mat4_world_to_cam_ * vec3_lamp_pos
200
201    :type: float3
202
203 .. data:: GPU_DYNAMIC_LAMP_DYNIMAT
204
205    Matrix that converts vector in camera space to lamp space.
206
207    Computed as:
208       mat4_world_to_lamp_ * mat4_cam_to_world_
209
210    :type: matrix4x4
211
212 .. data:: GPU_DYNAMIC_LAMP_DYNPERSMAT
213
214    Matrix that converts a vector in camera space to shadow buffer depth space.
215
216    Computed as:
217       mat4_perspective_to_depth_ * mat4_lamp_to_perspective_ * mat4_world_to_lamp_ * mat4_cam_to_world_.
218
219    .. _mat4_perspective_to_depth:
220
221    ``mat4_perspective_to_depth`` is a fixed matrix defined as follow::
222
223       0.5 0.0 0.0 0.5
224       0.0 0.5 0.0 0.5
225       0.0 0.0 0.5 0.5
226       0.0 0.0 0.0 1.0
227
228    .. note::
229
230       - There is one uniform of that type per lamp casting shadow in the scene.
231
232    :type: matrix4x4
233
234 .. data:: GPU_DYNAMIC_LAMP_DYNENERGY
235
236    See :class:`bpy.types.Lamp.energy`.
237
238    :type: float
239
240 .. data:: GPU_DYNAMIC_LAMP_DYNCOL
241
242    See :class:`bpy.types.Lamp.color`.
243
244    :type: float3
245
246 .. data:: GPU_DYNAMIC_LAMP_DISTANCE
247
248    See :class:`bpy.types.Lamp.distance`.
249
250    :type: float
251
252 .. data:: GPU_DYNAMIC_LAMP_ATT1
253
254    See
255    :class:`bpy.types.PointLamp.linear_attenuation`,
256    :class:`bpy.types.SpotLamp.linear_attenuation`.
257
258    :type: float
259
260 .. data:: GPU_DYNAMIC_LAMP_ATT2
261
262    See
263    :class:`bpy.types.PointLamp.quadratic_attenuation`,
264    :class:`bpy.types.SpotLamp.quadratic_attenuation`.
265
266    :type: float
267
268 .. data:: GPU_DYNAMIC_LAMP_SPOTSIZE
269
270    See :class:`bpy.types.SpotLamp.spot_size`.
271
272    :type: float
273
274 .. data:: GPU_DYNAMIC_LAMP_SPOTBLEND
275
276    See :class:`bpy.types.SpotLamp.spot_blend`.
277
278    :type: float
279
280
281 GLSL Sampler Uniforms
282 ^^^^^^^^^^^^^^^^^^^^^
283
284 .. data:: GPU_DYNAMIC_SAMPLER_2DBUFFER
285
286    Represents an internal texture used for certain effect
287    (color band, etc).
288
289    :type: integer
290
291 .. data:: GPU_DYNAMIC_SAMPLER_2DIMAGE
292
293    Represents a texture loaded from an image file.
294
295    :type: integer
296
297 .. data:: GPU_DYNAMIC_SAMPLER_2DSHADOW
298
299    Represents a texture loaded from a shadow buffer file.
300
301    :type: integer
302
303
304 GLSL Mist Uniforms
305 ^^^^^^^^^^^^^^^^^^
306
307 .. data:: GPU_DYNAMIC_MIST_ENABLE:
308
309    See :class:`bpy.types.WorldMistSettings.use_mist`.
310
311    :type: float (0 or 1)
312
313 .. data:: GPU_DYNAMIC_MIST_START
314
315    See :class:`bpy.types.WorldMistSettings.start`.
316
317    :type: float
318
319    See :class:`bpy.types.WorldMistSettings.depth`.
320
321 .. data:: GPU_DYNAMIC_MIST_DISTANCE
322
323    :type: float
324
325    See :class:`bpy.types.WorldMistSettings.intensity`.
326
327 .. data:: GPU_DYNAMIC_MIST_INTENSITY
328
329    :type: float
330
331 .. data:: GPU_DYNAMIC_MIST_TYPE
332
333    See :class:`bpy.types.WorldMistSettings.falloff`.
334
335    :type: float (used as an index into the type)
336
337 .. data:: GPU_DYNAMIC_MIST_COLOR
338
339
340 GLSL World Uniforms
341 ^^^^^^^^^^^^^^^^^^^
342
343 .. data:: GPU_DYNAMIC_HORIZON_COLOR
344
345    See :class:`bpy.types.World.horizon_color`.
346
347    :type: float3
348
349 .. data:: GPU_DYNAMIC_AMBIENT_COLOR
350
351    See :class:`bpy.types.World.ambient_color`.
352
353    :type: float3
354
355
356 GLSL Material Uniforms
357 ^^^^^^^^^^^^^^^^^^^^^^
358
359 .. data:: GPU_DYNAMIC_MAT_DIFFRGB
360
361    See :class:`bpy.types.Material.diffuse_color`.
362
363    :type: float3
364
365 .. data:: GPU_DYNAMIC_MAT_REF
366
367    See :class:`bpy.types.Material.diffuse_intensity`.
368
369    :type: float
370
371 .. data:: GPU_DYNAMIC_MAT_SPECRGB
372
373    See :class:`bpy.types.Material.specular_color`.
374
375    :type: float3
376
377 .. data:: GPU_DYNAMIC_MAT_SPEC
378
379    See :class:`bpy.types.Material.specular_intensity`.
380
381    :type: float
382
383 .. data:: GPU_DYNAMIC_MAT_HARD
384
385    See :class:`bpy.types.Material.specular_hardness`.
386
387    :type: float
388
389 .. data:: GPU_DYNAMIC_MAT_EMIT
390
391    See :class:`bpy.types.Material.emit`.
392
393    :type: float
394
395 .. data:: GPU_DYNAMIC_MAT_AMB
396
397    See :class:`bpy.types.Material.ambient`.
398
399    :type: float
400
401 .. data:: GPU_DYNAMIC_MAT_ALPHA
402
403    See :class:`bpy.types.Material.alpha`.
404
405    :type: float
406
407
408
409 GLSL Attribute Type
410 -------------------
411
412 .. _attribute-type:
413
414 Type of the vertex attribute used in the GLSL shader. Determines the mesh custom data
415 layer that contains the vertex attribute.
416
417 .. data:: CD_MTFACE
418
419    Vertex attribute is a UV Map. Data type is vector of 2 float.
420
421    There can be more than one attribute of that type, they are differenciated by name.
422    In blender, you can retrieve the attribute data with:
423
424    .. code-block:: python
425
426       mesh.uv_layers[attribute["name"]]
427
428 .. data:: CD_MCOL
429
430    Vertex attribute is color layer. Data type is vector 4 unsigned byte (RGBA).
431
432    There can be more than one attribute of that type, they are differenciated by name.
433    In blender you can retrieve the attribute data with:
434
435    .. code-block:: python
436
437       mesh.vertex_colors[attribute["name"]]
438
439 .. data:: CD_ORCO
440
441    Vertex attribute is original coordinates. Data type is vector 3 float.
442
443    There can be only 1 attribute of that type per shader.
444    In blender you can retrieve the attribute data with:
445
446    .. code-block:: python
447
448       mesh.vertices
449
450 .. data:: CD_TANGENT
451
452    Vertex attribute is the tangent vector. Data type is vector 4 float.
453
454    There can be only 1 attribute of that type per shader.
455    There is currently no way to retrieve this attribute data via the RNA API but a standalone
456    C function to compute the tangent layer from the other layers can be obtained from
457    blender.org.
458
459
460 Functions
461 =========
462
463 .. _export_shader:
464
465 .. function:: export_shader(scene,material)
466
467    Extracts the GLSL shader producing the visual effect of material in scene for the purpose of
468    reusing the shader in an external engine.
469
470    This function is meant to be used in material exporter
471    so that the GLSL shader can be exported entirely.
472
473    The return value is a dictionary containing the
474    shader source code and all associated data.
475
476    :arg scene: the scene in which the material in rendered.
477    :type scene: :class:`bpy.types.Scene`
478    :arg material: the material that you want to export the GLSL shader
479    :type material: :class:`bpy.types.Material`
480    :return: the shader source code and all associated data in a dictionary
481    :rtype: dictionary
482
483    The dictionary contains the following elements:
484
485    - ``["fragment"]``: string
486       fragment shader source code.
487
488    - ``["vertex"]``: string
489       vertex shader source code.
490
491    - ``["uniforms"]``: sequence
492       list of uniforms used in fragment shader, can be empty list. Each element of the
493       sequence is a dictionary with the following elements:
494
495       - ``["varname"]``: string
496          name of the uniform in the fragment shader. Always of the form 'unf<number>'.
497
498       - ``["datatype"]``: integer
499          data type of the uniform variable. Can be one of the following:
500
501          .. hlist::
502             :columns: 2
503
504             - :data:`gpu.GPU_DATA_1I` : use ``glUniform1i``
505             - :data:`gpu.GPU_DATA_1F` : use ``glUniform1fv``
506             - :data:`gpu.GPU_DATA_2F` : use ``glUniform2fv``
507             - :data:`gpu.GPU_DATA_3F` : use ``glUniform3fv``
508             - :data:`gpu.GPU_DATA_4F` : use ``glUniform4fv``
509             - :data:`gpu.GPU_DATA_9F` : use ``glUniformMatrix3fv``
510             - :data:`gpu.GPU_DATA_16F` : use ``glUniformMatrix4fv``
511
512       - ``["type"]``: integer
513          type of uniform, determines the origin and method of calculation. See uniform-type_.
514          Depending on the type, more elements will be be present.
515
516       - ``["lamp"]``: :class:`bpy.types.Object`
517          Reference to the lamp object from which the uniforms value are extracted.
518          Set for the following uniforms types:
519
520          .. hlist::
521             :columns: 2
522
523             - :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`
524             - :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`
525             - :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT`
526             - :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
527             - :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY`
528             - :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL`
529             - :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`
530
531          Notes:
532
533          - The uniforms
534            :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`,
535            :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`,
536            :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT` and
537            :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
538            refer to the lamp object position and orientation,
539            both of can be derived from the object world matrix:
540
541             .. code-block:: python
542
543                obmat = uniform["lamp"].matrix_world
544
545             where obmat is the mat4_lamp_to_world_ matrix of the lamp as a 2 dimensional array,
546             the lamp world location location is in ``obmat[3]``.
547
548          - The uniform types
549            :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY` and
550            :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL`
551            refer to the lamp data bloc that you get from:
552
553             .. code-block:: python
554
555                la = uniform["lamp"].data
556
557             from which you get ``lamp.energy`` and ``lamp.color``
558
559          - Lamp duplication is not supported: if you have duplicated lamps in your scene
560             (i.e. lamp that are instantiated by dupligroup, etc), this element will only
561             give you a reference to the orignal lamp and you will not know which instance
562             of the lamp it is refering too. You can still handle that case in the exporter
563             by distributing the uniforms amongst the duplicated lamps.
564
565       - ``["image"]``: :class:`bpy.types.Image`
566          Reference to the image databloc.
567          Set for uniform type
568          :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE`.
569          You can get the image data from:
570
571          .. code-block:: python
572
573             # full path to image file
574             uniform["image"].filepath
575             # image size as a 2-dimensional array of int
576             uniform["image"].size
577
578       - ``["texnumber"]``: integer
579          Channel number to which the texture is bound when drawing the object.
580          Set for uniform types
581          :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`,
582          :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE` and
583          :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`.
584
585          This is provided for information only: when reusing the shader outside blencer,
586          you are free to assign the textures to the channel of your choice and to pass
587          that number channel to the GPU in the uniform.
588
589       - ``["texpixels"]``: byte array
590          texture data for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`.
591          Although the corresponding uniform is a 2D sampler,
592          the texture is always a 1D texture of n x 1 pixel.
593          The texture size n is provided in ["texsize"] element.
594          These texture are only used for computer generated texture (colorband, etc).
595          The texture data is provided so that you can make a real image out of it in the exporter.
596
597       - ``["texsize"]``: integer
598          horizontal size of texture for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`.
599          The texture data is in ["texpixels"].
600
601    - ``["attributes"]``: sequence
602       list of attributes used in vertex shader, can be empty. Blender doesn't use
603       standard attributes except for vertex position and normal. All other vertex
604       attributes must be passed using the generic ``glVertexAttrib`` functions.
605       The attribute data can be found in the derived mesh custom data using RNA.
606       Each element of the sequence is a dictionary containing the following elements:
607
608       - ``["varname"]``: string
609          name of the uniform in the vertex shader. Always of the form 'att<number>'.
610
611       - ``["datatype"]``: integer
612          data type of vertex attribute, can be one of the following:
613
614          - :data:`gpu.GPU_DATA_2F`: use ``glVertexAttrib2fv``
615          - :data:`gpu.GPU_DATA_3F`: use ``glVertexAttrib3fv``
616          - :data:`gpu.GPU_DATA_4F`: use ``glVertexAttrib4fv``
617          - :data:`gpu.GPU_DATA_4UB`: use ``glVertexAttrib4ubv``
618
619       - ``["number"]``: integer
620          Generic attribute number. This is provided for information only.
621          Blender doesn't use ``glBindAttribLocation`` to place generic attributes at specific location,
622          it lets the shader compiler place the attributes automatically and query the
623          placement with ``glGetAttribLocation``.
624          The result of this placement is returned in this element.
625
626          When using this shader in a render engine, you should either use
627          ``glBindAttribLocation`` to force the attribute at this location or use
628          ``glGetAttribLocation`` to get the placement chosen by the compiler of your GPU.
629
630       - ``["type"]``: integer
631          type of the mesh custom data from which the vertex attribute is loaded.
632          See attribute-type_.
633
634       - ``["name"]``: string or integer
635          custom data layer name, used for attribute type :data:`gpu.CD_MTFACE` and :data:`gpu.CD_MCOL`.
636
637    Example:
638
639    .. code-block:: python
640
641       import gpu
642       # get GLSL shader of material Mat.001 in scene Scene.001
643       scene = bpy.data.scenes["Scene.001"]
644       material = bpy.data.materials["Mat.001"]
645       shader = gpu.export_shader(scene,material)
646       # scan the uniform list and find the images used in the shader
647       for uniform in shader["uniforms"]:
648           if uniform["type"] == gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE:
649               print("uniform {0} is using image {1}".format(uniform["varname"], uniform["image"].filepath))
650       # scan the attribute list and find the UV Map used in the shader
651       for attribute in shader["attributes"]:
652           if attribute["type"] == gpu.CD_MTFACE:
653               print("attribute {0} is using UV Map {1}".format(attribute["varname"], attribute["name"]))
654
655
656 Notes
657 =====
658
659 .. _mat4_lamp_to_perspective:
660
661 #. Calculation of the ``mat4_lamp_to_perspective`` matrix for a spot lamp.
662
663    The following pseudo code shows how the ``mat4_lamp_to_perspective`` matrix is computed
664    in blender for uniforms of :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` type:
665
666    .. code-block:: python
667
668       # Get the lamp datablock with:
669       lamp = bpy.data.objects[uniform["lamp"]].data
670
671       # Compute the projection matrix:
672       #  You will need these lamp attributes:
673       #  lamp.clipsta : near clip plane in world unit
674       #  lamp.clipend : far clip plane in world unit
675       #  lamp.spotsize : angle in degree of the spot light
676
677       # The size of the projection plane is computed with the usual formula:
678       wsize = lamp.clista * tan(lamp.spotsize/2)
679
680       # And the projection matrix:
681       mat4_lamp_to_perspective = glFrustum(-wsize, wsize, -wsize, wsize, lamp.clista, lamp.clipend)
682
683 #. Creation of the shadow map for a spot lamp.
684
685    The shadow map is the depth buffer of a render performed by placing the camera at the
686    spot light position. The size of the shadow map is given by the attribute ``lamp.bufsize``:
687    shadow map size in pixel, same size in both dimensions.