[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [40061] trunk/blender: GPU: add gpu python module with export_shader() function to export GLSL shader.
Benoit Bolsee
benoit.bolsee at online.be
Fri Sep 9 13:55:38 CEST 2011
Revision: 40061
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=40061
Author: ben2610
Date: 2011-09-09 11:55:38 +0000 (Fri, 09 Sep 2011)
Log Message:
-----------
GPU: add gpu python module with export_shader() function to export GLSL shader.
shader = gpu.export_shader(scene,material)
Returns the GLSL shader that blender generates to produce 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 a 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.
The full documentation is under sphinx.
Warning: there has been an API between the patch and this commit:
uniform['lamp'] and uniform['image'] now return python reference to
ID block instead of ID name as before. The X3D exporter that uses this
function must be adapted.
Modified Paths:
--------------
trunk/blender/source/blender/gpu/GPU_extensions.h
trunk/blender/source/blender/gpu/GPU_material.h
trunk/blender/source/blender/gpu/intern/gpu_codegen.c
trunk/blender/source/blender/gpu/intern/gpu_codegen.h
trunk/blender/source/blender/gpu/intern/gpu_extensions.c
trunk/blender/source/blender/gpu/intern/gpu_material.c
trunk/blender/source/blender/gpu/intern/gpu_shader_material.glsl
trunk/blender/source/blender/gpu/intern/gpu_shader_material.glsl.c
trunk/blender/source/blender/python/SConscript
trunk/blender/source/blender/python/intern/CMakeLists.txt
trunk/blender/source/blender/python/intern/bpy_interface.c
Added Paths:
-----------
trunk/blender/doc/python_api/rst/gpu.rst
trunk/blender/source/blender/python/intern/gpu.c
trunk/blender/source/blender/python/intern/gpu.h
Added: trunk/blender/doc/python_api/rst/gpu.rst
===================================================================
--- trunk/blender/doc/python_api/rst/gpu.rst (rev 0)
+++ trunk/blender/doc/python_api/rst/gpu.rst 2011-09-09 11:55:38 UTC (rev 40061)
@@ -0,0 +1,531 @@
+
+GPU functions (gpu)
+===================
+
+*****
+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 should be consider unstable. 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).
+
+.. module:: gpu
+
+*********
+Constants
+*********
+
+--------------
+GLSL data type
+--------------
+
+.. _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_
+
+.. data:: GPU_DATA_1I
+
+ one integer
+
+ :value: 1
+
+.. data:: GPU_DATA_1F
+
+ one float
+
+ :value: 2
+
+.. data:: GPU_DATA_2F
+
+ two floats
+
+ :value: 3
+
+.. data:: GPU_DATA_3F
+
+ three floats
+
+ :value: 4
+
+.. data:: GPU_DATA_4F
+
+ four floats
+
+ :value: 5
+
+.. data:: GPU_DATA_9F
+
+ matrix 3x3 in column-major order
+
+ :value: 6
+
+.. data:: GPU_DATA_16F
+
+ matrix 4x4 in column-major order
+
+ :value: 7
+
+.. data:: GPU_DATA_4UB
+
+ four unsigned byte
+
+ :value: 8
+
+-----------------
+GLSL uniform type
+-----------------
+
+.. _uniform-type:
+
+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:
+ .. _mat4_world_to_cam:
+
+ *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:
+ .. _mat4_world_to_object:
+
+ *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:
+ .. _mat4_world_to_lamp:
+
+ *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.
+
+.. data:: GPU_DYNAMIC_OBJECT_VIEWMAT
+
+ The uniform is a 4x4 GL matrix that converts world coordinates to
+ camera coordinates (see mat4_world_to_cam_). Can be set once per frame.
+ There is at most one uniform of that type per shader.
+
+ :value: 1
+
+.. data:: GPU_DYNAMIC_OBJECT_MAT
+
+ The uniform is a 4x4 GL matrix that converts object coordinates
+ to world coordinates (see mat4_object_to_world_). Must be set before drawing the object.
+ There is at most one uniform of that type per shader.
+
+ :value: 2
+
+.. data:: 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_).
+ Can be set once per frame.
+ There is at most one uniform of that type per shader.
+
+ :value: 3
+
+.. data:: GPU_DYNAMIC_OBJECT_IMAT
+
+ The uniform is a 4x4 GL matrix that converts world coodinates
+ to object coordinates (see mat4_world_to_object_).
+ Must be set before drawing the object.
+ There is at most one uniform of that type per shader.
+
+ :value: 4
+
+.. data:: GPU_DYNAMIC_OBJECT_COLOR
+
+ The uniform is a vector of 4 float representing a RGB color + alpha defined at object level.
+ Each values between 0.0 and 1.0. In blender it corresponds to the 'color' attribute of the object.
+ Must be set before drawing the object.
+ There is at most one uniform of that type per shader.
+
+ :value: 5
+
+.. data:: GPU_DYNAMIC_LAMP_DYNVEC
+
+ The uniform is a vector of 3 float representing the direction of light in camera space.
+ In Blender, this is computed by
+
+ mat4_world_to_cam_ * (-vec3_lamp_Z_axis)
+
+ as the lamp Z axis points to the opposite direction of light.
+ The norm of the vector should be unity. Can be set once per frame.
+ There is one uniform of that type per lamp lighting the material.
+
+ :value: 6
+
+.. data:: GPU_DYNAMIC_LAMP_DYNCO
+
+ The uniform is a vector of 3 float representing the position of the light in camera space.
+ Computed as
+
+ mat4_world_to_cam_ * vec3_lamp_pos
+
+ Can be set once per frame.
+ There is one uniform of that type per lamp lighting the material.
+
+ :value: 7
+
+.. data:: GPU_DYNAMIC_LAMP_DYNIMAT
+
+ The uniform is a 4x4 GL matrix that converts vector in camera space to lamp space.
+ Computed as
+
+ mat4_world_to_lamp_ * mat4_cam_to_world_
+
+ Can be set once per frame.
+ There is one uniform of that type per lamp lighting the material.
+
+ :value: 8
+
+.. data:: GPU_DYNAMIC_LAMP_DYNPERSMAT
+
+ The uniform is a 4x4 GL 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:
+
+ *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
+
+ This uniform can be set once per frame. There is one uniform of that type per lamp casting shadow in the scene.
+
+ :value: 9
+
+.. data:: GPU_DYNAMIC_LAMP_DYNENERGY
+
+ The uniform is a single float representing the lamp energy. In blender it corresponds
+ to the 'energy' attribute of the lamp data block.
+ There is one uniform of that type per lamp lighting the material.
+
+ :value: 10
+
+.. data:: GPU_DYNAMIC_LAMP_DYNCOL
+
+ The uniform is a vector of 3 float representing the lamp color.
+ Color elements are between 0.0 and 1.0. In blender it corresponds
+ to the 'color' attribute of the lamp data block.
+ There is one uniform of that type per lamp lighting the material.
+
+ :value: 11
+
+.. data:: GPU_DYNAMIC_SAMPLER_2DBUFFER
+
+ The uniform is an integer representing an internal texture used for certain effect
+ (color band, etc).
+
+ :value: 12
+
+.. data:: GPU_DYNAMIC_SAMPLER_2DIMAGE
+
+ The uniform is an integer representing a texture loaded from an image file.
+
+ :value: 13
+
+.. data:: GPU_DYNAMIC_SAMPLER_2DSHADOW
+
+ The uniform is an integer representing a shadow buffer corresponding to a lamp
+ casting shadow.
+
+ :value: 14
+
+-------------------
+GLSL attribute type
+-------------------
+
+.. _attribute-type:
+
+Type of the vertex attribute used in the GLSL shader. Determines the mesh custom data
+layer that contains the vertex attribute.
+
+.. data:: CD_MTFACE
+
+ Vertex attribute is a UV layer. 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:
+
+ .. code-block:: python
+
+ mesh.uv_textures[attribute['name']]
+
+ :value: 5
+
+.. data:: 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:
+
+ .. code-block:: python
+
+ mesh.vertex_colors[attribute['name']]
+
+ :value: 6
+
+.. data:: 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:
+
+ .. code-block:: python
+
+ mesh.vertices
+
+ :value: 14
+
+.. data:: 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.
+
+ :value: 18
+
+*********
+Functions
+*********
+
+.. _export_shader:
+
+.. function:: 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.
+
+ :arg scene: the scene in which the material in rendered.
+ :type scene: :class:`bpy.types.Scene`
+ :arg material: the material that you want to export the GLSL shader
+ :type material: :class:`bpy.types.Material`
+ :return: the shader source code and all associated data in a dictionary
+ :rtype: 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>'.
+
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list