← Back to branch summary

~siretart/ubuntu/utopic/blender/libav10

« back to all changes in this revision

Viewing changes to doc/python_api/rst/gpu.rst

  • Committer: Package Import Robot
  • Author(s): Matteo F. Vescovi
  • Date: 2012-07-23 08:54:18 UTC
  • mfrom: (14.2.16 sid)
  • mto: (14.2.19 sid)
  • mto: This revision was merged to the branch mainline in revision 42.
  • Revision ID: package-import@ubuntu.com-20120723085418-9foz30v6afaf5ffs
Tags: 2.63a-2
http://bugs.debian.org/658075
* debian/: Cycles support added (Closes: #658075)
  For now, this top feature has been enabled only
  on [any-amd64 any-i386] architectures because
  of OpenImageIO failing on all others
* debian/: scripts installation path changed
  from /usr/lib to /usr/share:
  + debian/patches/: patchset re-worked for path changing
  + debian/control: "Breaks" field added on yafaray-exporter

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 should be consider unstable. The data exposed by the API
 
20
   are are closely related to Blender's internal GLSL code and may change if the GLSL code
 
21
   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
   :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
   .. code-block:: python
 
515
 
 
516
      #Get the lamp datablock with:
 
517
      lamp = bpy.data.objects[uniform["lamp"]].data
 
518
 
 
519
      # Compute the projection matrix:
 
520
      #  You will need these lamp attributes:
 
521
      #  lamp.clipsta : near clip plane in world unit
 
522
      #  lamp.clipend : far clip plane in world unit
 
523
      #  lamp.spotsize : angle in degree of the spot light
 
524
 
 
525
      # The size of the projection plane is computed with the usual formula:
 
526
      wsize = lamp.clista * tan(lamp.spotsize/2)
 
527
 
 
528
      #And the projection matrix:
 
529
      mat4_lamp_to_perspective = glFrustum(-wsize, wsize, -wsize, wsize, lamp.clista, lamp.clipend)
 
530
 
 
531
2. Creation of the shadow map for a spot lamp.
 
532
 
 
533
   The shadow map is the depth buffer of a render performed by placing the camera at the
 
534
   spot light position. The size of the shadow map is given by the attribute lamp.bufsize :
 
535
   shadow map size in pixel, same size in both dimensions.