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 float representing the bumpmap scaling.
 266
 267    :value: 14
 268
 269 .. data:: GPU_DYNAMIC_OBJECT_AUTOBUMPSCALE
 270
 271    The uniform is an integer representing a shadow buffer corresponding to a lamp
 272    casting shadow.
 273
 274    :value: 15
 275
 276
 277 GLSL attribute type
 278 -------------------
 279
 280 .. _attribute-type:
 281
 282 Type of the vertex attribute used in the GLSL shader. Determines the mesh custom data
 283 layer that contains the vertex attribute.
 284
 285 .. data:: CD_MTFACE
 286
 287    Vertex attribute is a UV Map. Data type is vector of 2 float.
 288
 289    There can be more than one attribute of that type, they are differenciated by name.
 290    In blender, you can retrieve the attribute data with:
 291
 292    .. code-block:: python
 293
 294       mesh.uv_textures[attribute["name"]]
 295
 296    :value: 5
 297
 298 .. data:: CD_MCOL
 299
 300    Vertex attribute is color layer. Data type is vector 4 unsigned byte (RGBA).
 301
 302    There can be more than one attribute of that type, they are differenciated by name.
 303    In blender you can retrieve the attribute data with:
 304
 305    .. code-block:: python
 306
 307       mesh.vertex_colors[attribute["name"]]
 308
 309    :value: 6
 310
 311 .. data:: CD_ORCO
 312
 313    Vertex attribute is original coordinates. Data type is vector 3 float.
 314
 315    There can be only 1 attribute of that type per shader.
 316    In blender you can retrieve the attribute data with:
 317
 318    .. code-block:: python
 319
 320       mesh.vertices
 321
 322    :value: 14
 323
 324 .. data:: CD_TANGENT
 325
 326    Vertex attribute is the tangent vector. Data type is vector 4 float.
 327
 328    There can be only 1 attribute of that type per shader.
 329    There is currently no way to retrieve this attribute data via the RNA API but a standalone
 330    C function to compute the tangent layer from the other layers can be obtained from
 331    blender.org.
 332
 333    :value: 18
 334
 335
 336 Functions
 337 =========
 338
 339 .. _export_shader:
 340
 341 .. function:: export_shader(scene,material)
 342
 343    Extracts the GLSL shader producing the visual effect of material in scene for the purpose of
 344    reusing the shader in an external engine. This function is meant to be used in material exporter
 345    so that the GLSL shader can be exported entirely. The return value is a dictionary containing the
 346    shader source code and all associated data.
 347
 348    :arg scene: the scene in which the material in rendered.
 349    :type scene: :class:`bpy.types.Scene`
 350    :arg material: the material that you want to export the GLSL shader
 351    :type material: :class:`bpy.types.Material`
 352    :return: the shader source code and all associated data in a dictionary
 353    :rtype: dictionary
 354
 355    The dictionary contains the following elements:
 356
 357    * ["fragment"] : string
 358       fragment shader source code.
 359
 360    * ["vertex"] : string
 361       vertex shader source code.
 362
 363    * ["uniforms"] : sequence
 364       list of uniforms used in fragment shader, can be empty list. Each element of the
 365       sequence is a dictionary with the following elements:
 366
 367       * ["varname"] : string
 368          name of the uniform in the fragment shader. Always of the form 'unf<number>'.
 369
 370       * ["datatype"] : integer
 371          data type of the uniform variable. Can be one of the following:
 372
 373          * :data:`gpu.GPU_DATA_1I` : use glUniform1i
 374          * :data:`gpu.GPU_DATA_1F` : use glUniform1fv
 375          * :data:`gpu.GPU_DATA_2F` : use glUniform2fv
 376          * :data:`gpu.GPU_DATA_3F` : use glUniform3fv
 377          * :data:`gpu.GPU_DATA_4F` : use glUniform4fv
 378          * :data:`gpu.GPU_DATA_9F` : use glUniformMatrix3fv
 379          * :data:`gpu.GPU_DATA_16F` : use glUniformMatrix4fv
 380
 381       * ["type"] : integer
 382          type of uniform, determines the origin and method of calculation. See uniform-type_.
 383          Depending on the type, more elements will be be present.
 384
 385       * ["lamp"] : :class:`bpy.types.Object`
 386          Reference to the lamp object from which the uniforms value are extracted. Set for the following uniforms types:
 387
 388          .. hlist::
 389             :columns: 3
 390
 391             * :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`
 392             * :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`
 393             * :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT`
 394             * :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
 395             * :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY`
 396             * :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL`
 397             * :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`
 398
 399          Notes:
 400
 401          * 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`
 402             refer to the lamp object position and orientation, both of can be derived from the object world matrix:
 403
 404             .. code-block:: python
 405
 406                obmat = uniform["lamp"].matrix_world
 407
 408             where obmat is the mat4_lamp_to_world_ matrix of the lamp as a 2 dimensional array,
 409             the lamp world location location is in obmat[3].
 410
 411          * 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:
 412
 413             .. code-block:: python
 414
 415                la = uniform["lamp"].data
 416
 417             from which you get la.energy and la.color
 418
 419          * Lamp duplication is not supported: if you have duplicated lamps in your scene
 420             (i.e. lamp that are instantiated by dupligroup, etc), this element will only
 421             give you a reference to the orignal lamp and you will not know which instance
 422             of the lamp it is refering too. You can still handle that case in the exporter
 423             by distributing the uniforms amongst the duplicated lamps.
 424
 425       * ["image"] : :class:`bpy.types.Image`
 426          Reference to the image databloc. Set for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE`. You can get the image data from:
 427
 428          .. code-block:: python
 429
 430             # full path to image file
 431             uniform["image"].filepath
 432             # image size as a 2-dimensional array of int
 433             uniform["image"].size
 434
 435       * ["texnumber"] : integer
 436          Channel number to which the texture is bound when drawing the object.
 437          Set for uniform types :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`, :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE` and :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`.
 438
 439          This is provided for information only: when reusing the shader outside blencer,
 440          you are free to assign the textures to the channel of your choice and to pass
 441          that number channel to the GPU in the uniform.
 442
 443       * ["texpixels"] : byte array
 444          texture data for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`. Although
 445          the corresponding uniform is a 2D sampler, the texture is always a 1D texture
 446          of n x 1 pixel. The texture size n is provided in ["texsize"] element.
 447          These texture are only used for computer generated texture (colorband, etc).
 448          The texture data is provided so that you can make a real image out of it in the
 449          exporter.
 450
 451       * ["texsize"] : integer
 452          horizontal size of texture for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`.
 453          The texture data is in ["texpixels"].
 454
 455    * ["attributes"] : sequence
 456       list of attributes used in vertex shader, can be empty. Blender doesn't use
 457       standard attributes except for vertex position and normal. All other vertex
 458       attributes must be passed using the generic glVertexAttrib functions.
 459       The attribute data can be found in the derived mesh custom data using RNA.
 460       Each element of the sequence is a dictionary containing the following elements:
 461
 462       * ["varname"] : string
 463          name of the uniform in the vertex shader. Always of the form 'att<number>'.
 464
 465       * ["datatype"] : integer
 466          data type of vertex attribute, can be one of the following:
 467
 468          * :data:`gpu.GPU_DATA_2F` : use glVertexAttrib2fv
 469          * :data:`gpu.GPU_DATA_3F` : use glVertexAttrib3fv
 470          * :data:`gpu.GPU_DATA_4F` : use glVertexAttrib4fv
 471          * :data:`gpu.GPU_DATA_4UB` : use glVertexAttrib4ubv
 472
 473       * ["number"] : integer
 474          generic attribute number. This is provided for information only. Blender
 475          doesn't use glBindAttribLocation to place generic attributes at specific location,
 476          it lets the shader compiler place the attributes automatically and query the
 477          placement with glGetAttribLocation. The result of this placement is returned in
 478          this element.
 479
 480          When using this shader in a render engine, you should either use
 481          glBindAttribLocation to force the attribute at this location or use
 482          glGetAttribLocation to get the placement chosen by the compiler of your GPU.
 483
 484       * ["type"] : integer
 485          type of the mesh custom data from which the vertex attribute is loaded.
 486          See attribute-type_.
 487
 488       * ["name"] : string or integer
 489          custom data layer name, used for attribute type :data:`gpu.CD_MTFACE` and :data:`gpu.CD_MCOL`.
 490
 491    Example:
 492
 493    .. code-block:: python
 494
 495       import gpu
 496       # get GLSL shader of material Mat.001 in scene Scene.001
 497       scene = bpy.data.scenes["Scene.001"]
 498       material = bpy.data.materials["Mat.001"]
 499       shader = gpu.export_shader(scene,material)
 500       # scan the uniform list and find the images used in the shader
 501       for uniform in shader["uniforms"]:
 502           if uniform["type"] == gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE:
 503               print("uniform {0} is using image {1}".format(uniform["varname"], uniform["image"].filepath))
 504       # scan the attribute list and find the UV Map used in the shader
 505       for attribute in shader["attributes"]:
 506           if attribute["type"] == gpu.CD_MTFACE:
 507               print("attribute {0} is using UV Map {1}".format(attribute["varname"], attribute["name"]))
 508
 509
 510 Notes
 511 =====
 512
 513 .. _mat4_lamp_to_perspective:
 514
 515 1. Calculation of the *mat4_lamp_to_perspective* matrix for a spot lamp.
 516
 517    The following pseudo code shows how the *mat4_lamp_to_perspective* matrix is computed
 518    in blender for uniforms of :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` type::
 519
 520    .. code-block:: python
 521
 522       #Get the lamp datablock with:
 523       lamp = bpy.data.objects[uniform["lamp"]].data
 524
 525       # Compute the projection matrix:
 526       #  You will need these lamp attributes:
 527       #  lamp.clipsta : near clip plane in world unit
 528       #  lamp.clipend : far clip plane in world unit
 529       #  lamp.spotsize : angle in degree of the spot light
 530
 531       # The size of the projection plane is computed with the usual formula:
 532       wsize = lamp.clista * tan(lamp.spotsize/2)
 533
 534       #And the projection matrix:
 535       mat4_lamp_to_perspective = glFrustum(-wsize, wsize, -wsize, wsize, lamp.clista, lamp.clipend)
 536
 537 2. Creation of the shadow map for a spot lamp.
 538
 539    The shadow map is the depth buffer of a render performed by placing the camera at the
 540    spot light position. The size of the shadow map is given by the attribute lamp.bufsize :
 541    shadow map size in pixel, same size in both dimensions.