GPU functions (gpu)

This module provides access to materials GLSL shaders.

Submodules:

• GPU Off-Screen Buffer (gpu.offscreen)

Intro

Module to provide functions concerning the GPU implementation in Blender, in particular the GLSL shaders that blender generates automatically to render materials in the 3D view and in the game engine.

Warning

The API provided by this module is subject to change. The data exposed by the API are are closely related to Blender’s internal GLSL code and may change if the GLSL code is modified (e.g. new uniform type).

Constants

GLSL Data Type

Type of GLSL data. For shader uniforms, the data type determines which glUniform function variant to use to send the uniform value to the GPU. For vertex attributes, the data type determines which glVertexAttrib function variant to use to send the vertex attribute to the GPU.

See export_shader

gpu.GPU_DATA_1I

one integer

gpu.GPU_DATA_1F

one float

gpu.GPU_DATA_2F

two floats

gpu.GPU_DATA_3F

three floats

gpu.GPU_DATA_4F

four floats

gpu.GPU_DATA_9F

matrix 3x3 in column-major order

gpu.GPU_DATA_16F

matrix 4x4 in column-major order

gpu.GPU_DATA_4UB

four unsigned byte

GLSL Uniform Types

Constants that specify the type of uniform used in a GLSL shader. The uniform type determines the data type, origin and method of calculation used by Blender to compute the uniform value.

The calculation of some of the uniforms is based on matrices available in the scene:

mat4_cam_to_world

Model matrix of the camera. OpenGL 4x4 matrix that converts camera local coordinates to world coordinates. In blender this is obtained from the ‘matrix_world’ attribute of the camera object.

Some uniform will need the mat4_world_to_cam matrix computed as the inverse of this matrix.

mat4_object_to_world

Model matrix of the object that is being rendered. OpenGL 4x4 matric that converts object local coordinates to world coordinates. In blender this is obtained from the ‘matrix_world’ attribute of the object.

Some uniform will need the mat4_world_to_object matrix, computed as the inverse of this matrix.

mat4_lamp_to_world

Model matrix of the lamp lighting the object. OpenGL 4x4 matrix that converts lamp local coordinates to world coordinates. In blender this is obtained from the ‘matrix_world’ attribute of the lamp object.

Some uniform will need the mat4_world_to_lamp matrix computed as the inverse of this matrix.

Note

Any uniforms used for view projections or transformations (object, lamp matrices for eg), can only be set once per frame.

GLSL Object Uniforms

Note

• Object transformations and color must be set before drawing the object.

• There is at most one uniform of these types per shader.

gpu.GPU_DYNAMIC_OBJECT_VIEWMAT

A matrix that converts world coordinates to camera coordinates (see mat4_world_to_cam).

Type

matrix4x4

gpu.GPU_DYNAMIC_OBJECT_MAT

A matrix that converts object coordinates to world coordinates (see mat4_object_to_world).

Type

matrix4x4

gpu.GPU_DYNAMIC_OBJECT_VIEWIMAT

The uniform is a 4x4 GL matrix that converts coordinates in camera space to world coordinates (see mat4_cam_to_world).

Type

matrix4x4

gpu.GPU_DYNAMIC_OBJECT_IMAT

The uniform is a 4x4 GL matrix that converts world coodinates to object coordinates (see mat4_world_to_object).

Type

matrix4x4

gpu.GPU_DYNAMIC_OBJECT_COLOR

An RGB color + alpha defined at object level. Each values between 0.0 and 1.0.

See bpy.types.Object.color.

Type

float4

gpu.GPU_DYNAMIC_OBJECT_AUTOBUMPSCALE

Multiplier for bump-map scaling.

Type

float

GLSL Lamp Uniforms

Note

There is one uniform of that type per lamp lighting the material.

gpu.GPU_DYNAMIC_LAMP_DYNVEC

Represents the direction of light in camera space.

Computed as:

mat4_world_to_cam * (-vec3_lamp_Z_axis)

Note

• The lamp Z axis points to the opposite direction of light.

• The norm of the vector should be unit length.

Type

float3

gpu.GPU_DYNAMIC_LAMP_DYNCO

Represents the position of the light in camera space.

Computed as:

mat4_world_to_cam * vec3_lamp_pos

Type

float3

gpu.GPU_DYNAMIC_LAMP_DYNIMAT

Matrix that converts vector in camera space to lamp space.

Computed as:

mat4_world_to_lamp * mat4_cam_to_world

Type

matrix4x4

gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT

Matrix that converts a vector in camera space to shadow buffer depth space.

Computed as:

mat4_perspective_to_depth * mat4_lamp_to_perspective * mat4_world_to_lamp * mat4_cam_to_world.

mat4_perspective_to_depth is a fixed matrix defined as follow:

0.5 0.0 0.0 0.5
0.0 0.5 0.0 0.5
0.0 0.0 0.5 0.5
0.0 0.0 0.0 1.0

Note

• There is one uniform of that type per lamp casting shadow in the scene.

Type

matrix4x4

gpu.GPU_DYNAMIC_LAMP_DYNENERGY

See bpy.types.Lamp.energy.

Type

float

gpu.GPU_DYNAMIC_LAMP_DYNCOL

See bpy.types.Lamp.color.

Type

float3

gpu.GPU_DYNAMIC_LAMP_DISTANCE

See bpy.types.Lamp.distance.

Type

float

gpu.GPU_DYNAMIC_LAMP_ATT1

See bpy.types.PointLamp.linear_attenuation, bpy.types.SpotLamp.linear_attenuation.

Type

float

gpu.GPU_DYNAMIC_LAMP_ATT2

See bpy.types.PointLamp.quadratic_attenuation, bpy.types.SpotLamp.quadratic_attenuation.

Type

float

gpu.GPU_DYNAMIC_LAMP_SPOTSIZE

See bpy.types.SpotLamp.spot_size.

Type

float

gpu.GPU_DYNAMIC_LAMP_SPOTBLEND

See bpy.types.SpotLamp.spot_blend.

Type

float

gpu.GPU_DYNAMIC_LAMP_SPOTSCALE

Represents the SpotLamp local scale.

Type

float2

GLSL Sampler Uniforms

gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER

Represents an internal texture used for certain effect (color band, etc).

Type

integer

gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE

Represents a texture loaded from an image file.

Type

integer

gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW

Represents a texture loaded from a shadow buffer file.

Type

integer

GLSL Mist Uniforms

GPU_DYNAMIC_MIST_ENABLE:

See bpy.types.WorldMistSettings.use_mist.

Type

float (0 or 1)

gpu.GPU_DYNAMIC_MIST_START

See bpy.types.WorldMistSettings.start.

Type

float

See bpy.types.WorldMistSettings.depth.

gpu.GPU_DYNAMIC_MIST_DISTANCE

Type

float

See bpy.types.WorldMistSettings.intensity.

gpu.GPU_DYNAMIC_MIST_INTENSITY

Type

float

gpu.GPU_DYNAMIC_MIST_TYPE

See bpy.types.WorldMistSettings.falloff.

Type

float (used as an index into the type)

gpu.GPU_DYNAMIC_MIST_COLOR

GLSL World Uniforms

gpu.GPU_DYNAMIC_HORIZON_COLOR

See bpy.types.World.horizon_color.

Type

float3

gpu.GPU_DYNAMIC_AMBIENT_COLOR

See bpy.types.World.ambient_color.

Type

float3

GLSL Material Uniforms

gpu.GPU_DYNAMIC_MAT_DIFFRGB

See bpy.types.Material.diffuse_color.

Type

float3

gpu.GPU_DYNAMIC_MAT_REF

See bpy.types.Material.diffuse_intensity.

Type

float

gpu.GPU_DYNAMIC_MAT_SPECRGB

See bpy.types.Material.specular_color.

Type

float3

gpu.GPU_DYNAMIC_MAT_SPEC

See bpy.types.Material.specular_intensity.

Type

float

gpu.GPU_DYNAMIC_MAT_HARD

See bpy.types.Material.specular_hardness.

Type

float

gpu.GPU_DYNAMIC_MAT_EMIT

See bpy.types.Material.emit.

Type

float

gpu.GPU_DYNAMIC_MAT_AMB

See bpy.types.Material.ambient.

Type

float

gpu.GPU_DYNAMIC_MAT_ALPHA

See bpy.types.Material.alpha.

Type

float

GLSL Attribute Type

Type of the vertex attribute used in the GLSL shader. Determines the mesh custom data layer that contains the vertex attribute.

gpu.CD_MTFACE

Vertex attribute is a UV Map. Data type is vector of 2 float.

There can be more than one attribute of that type, they are differenciated by name. In blender, you can retrieve the attribute data with:

mesh.uv_layers[attribute["name"]]

gpu.CD_MCOL

Vertex attribute is color layer. Data type is vector 4 unsigned byte (RGBA).

There can be more than one attribute of that type, they are differenciated by name. In blender you can retrieve the attribute data with:

mesh.vertex_colors[attribute["name"]]

gpu.CD_ORCO

Vertex attribute is original coordinates. Data type is vector 3 float.

There can be only 1 attribute of that type per shader. In blender you can retrieve the attribute data with:

mesh.vertices

gpu.CD_TANGENT

Vertex attribute is the tangent vector. Data type is vector 4 float.

There can be only 1 attribute of that type per shader. There is currently no way to retrieve this attribute data via the RNA API but a standalone C function to compute the tangent layer from the other layers can be obtained from blender.org.

Functions

gpu.export_shader(scene, material)

Extracts the GLSL shader producing the visual effect of material in scene for the purpose of reusing the shader in an external engine.

This function is meant to be used in material exporter so that the GLSL shader can be exported entirely.

The return value is a dictionary containing the shader source code and all associated data.

Parameters

• scene (bpy.types.Scene) – the scene in which the material in rendered.

• material (bpy.types.Material) – the material that you want to export the GLSL shader

Returns

the shader source code and all associated data in a dictionary

Return type

dictionary

The dictionary contains the following elements:

• ["fragment"]: string

  fragment shader source code.

• ["vertex"]: string

  vertex shader source code.

• ["uniforms"]: sequence

  list of uniforms used in fragment shader, can be empty list. Each element of the sequence is a dictionary with the following elements:

  • ["varname"]: string

    name of the uniform in the fragment shader. Always of the form ‘unf<number>’.

  • ["datatype"]: integer

    data type of the uniform variable. Can be one of the following:

    gpu.GPU_DATA_1I : use glUniform1i gpu.GPU_DATA_1F : use glUniform1fv gpu.GPU_DATA_2F : use glUniform2fv gpu.GPU_DATA_3F : use glUniform3fv

    gpu.GPU_DATA_4F : use glUniform4fv gpu.GPU_DATA_9F : use glUniformMatrix3fv gpu.GPU_DATA_16F : use glUniformMatrix4fv

  • ["type"]: integer

    type of uniform, determines the origin and method of calculation. See uniform-type. Depending on the type, more elements will be be present.

  • ["lamp"]: bpy.types.Object

    Reference to the lamp object from which the uniforms value are extracted. Set for the following uniforms types:

    gpu.GPU_DYNAMIC_LAMP_DYNVEC gpu.GPU_DYNAMIC_LAMP_DYNCO gpu.GPU_DYNAMIC_LAMP_DYNIMAT gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT

    gpu.GPU_DYNAMIC_LAMP_DYNENERGY gpu.GPU_DYNAMIC_LAMP_DYNCOL gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW

    Notes:

    • The uniforms gpu.GPU_DYNAMIC_LAMP_DYNVEC, gpu.GPU_DYNAMIC_LAMP_DYNCO, gpu.GPU_DYNAMIC_LAMP_DYNIMAT and gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT refer to the lamp object position and orientation, both of can be derived from the object world matrix:

      obmat = uniform["lamp"].matrix_world
      

      where obmat is the mat4_lamp_to_world matrix of the lamp as a 2 dimensional array, the lamp world location location is in obmat[3].

    • The uniform types gpu.GPU_DYNAMIC_LAMP_DYNENERGY and gpu.GPU_DYNAMIC_LAMP_DYNCOL refer to the lamp data bloc that you get from:

      la = uniform["lamp"].data
      

      from which you get lamp.energy and lamp.color

    • Lamp duplication is not supported: if you have duplicated lamps in your scene

      (i.e. lamp that are instantiated by dupligroup, etc), this element will only give you a reference to the orignal lamp and you will not know which instance of the lamp it is refering too. You can still handle that case in the exporter by distributing the uniforms amongst the duplicated lamps.

  • ["image"]: bpy.types.Image

    Reference to the image databloc. Set for uniform type gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE. You can get the image data from:

    # full path to image file
    uniform["image"].filepath
    # image size as a 2-dimensional array of int
    uniform["image"].size
    

  • ["texnumber"]: integer

    Channel number to which the texture is bound when drawing the object. Set for uniform types gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER, gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE and gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW.

    This is provided for information only: when reusing the shader outside blencer, you are free to assign the textures to the channel of your choice and to pass that number channel to the GPU in the uniform.

  • ["texpixels"]: byte array

    texture data for uniform type gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER. Although the corresponding uniform is a 2D sampler, the texture is always a 1D texture of n x 1 pixel. The texture size n is provided in [“texsize”] element. These texture are only used for computer generated texture (colorband, etc). The texture data is provided so that you can make a real image out of it in the exporter.

  • ["texsize"]: integer

    horizontal size of texture for uniform type gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER. The texture data is in [“texpixels”].

• ["attributes"]: sequence

  list of attributes used in vertex shader, can be empty. Blender doesn’t use standard attributes except for vertex position and normal. All other vertex attributes must be passed using the generic glVertexAttrib functions. The attribute data can be found in the derived mesh custom data using RNA. Each element of the sequence is a dictionary containing the following elements:

  • ["varname"]: string

    name of the uniform in the vertex shader. Always of the form ‘att<number>’.

  • ["datatype"]: integer

    data type of vertex attribute, can be one of the following:

    • gpu.GPU_DATA_2F: use glVertexAttrib2fv

    • gpu.GPU_DATA_3F: use glVertexAttrib3fv

    • gpu.GPU_DATA_4F: use glVertexAttrib4fv

    • gpu.GPU_DATA_4UB: use glVertexAttrib4ubv

  • ["number"]: integer

    Generic attribute number. This is provided for information only. Blender doesn’t use glBindAttribLocation to place generic attributes at specific location, it lets the shader compiler place the attributes automatically and query the placement with glGetAttribLocation. The result of this placement is returned in this element.

    When using this shader in a render engine, you should either use glBindAttribLocation to force the attribute at this location or use glGetAttribLocation to get the placement chosen by the compiler of your GPU.

  • ["type"]: integer

    type of the mesh custom data from which the vertex attribute is loaded. See attribute-type.

  • ["name"]: string or integer

    custom data layer name, used for attribute type gpu.CD_MTFACE and gpu.CD_MCOL.

Example:

import gpu
# get GLSL shader of material Mat.001 in scene Scene.001
scene = bpy.data.scenes["Scene.001"]
material = bpy.data.materials["Mat.001"]
shader = gpu.export_shader(scene,material)
# scan the uniform list and find the images used in the shader
for uniform in shader["uniforms"]:
    if uniform["type"] == gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE:
        print("uniform {0} is using image {1}".format(uniform["varname"], uniform["image"].filepath))
# scan the attribute list and find the UV Map used in the shader
for attribute in shader["attributes"]:
    if attribute["type"] == gpu.CD_MTFACE:
        print("attribute {0} is using UV Map {1}".format(attribute["varname"], attribute["name"]))

Notes

1. Calculation of the mat4_lamp_to_perspective matrix for a spot lamp.

   The following pseudo code shows how the mat4_lamp_to_perspective matrix is computed in blender for uniforms of gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT type:

   # Get the lamp datablock with:
   lamp = bpy.data.objects[uniform["lamp"]].data
   
   # Compute the projection matrix:
   #  You will need these lamp attributes:
   #  lamp.clipsta : near clip plane in world unit
   #  lamp.clipend : far clip plane in world unit
   #  lamp.spotsize : angle in degree of the spot light
   
   # The size of the projection plane is computed with the usual formula:
   wsize = lamp.clista * tan(lamp.spotsize/2)
   
   # And the projection matrix:
   mat4_lamp_to_perspective = glFrustum(-wsize, wsize, -wsize, wsize, lamp.clista, lamp.clipend)
   

2. Creation of the shadow map for a spot lamp.

   The shadow map is the depth buffer of a render performed by placing the camera at the spot light position. The size of the shadow map is given by the attribute lamp.bufsize: shadow map size in pixel, same size in both dimensions.