[Bf-blender-cvs] [1c5b15e] master: Doc: update Python 'gpu' module reference
Campbell Barton
noreply at git.blender.org
Mon Sep 7 08:17:27 CEST 2015
Commit: 1c5b15eab3d6673ea0e5c1dea6d5d016880e64f6
Author: Campbell Barton
Date: Mon Sep 7 16:02:46 2015 +1000
Branches: master
https://developer.blender.org/rB1c5b15eab3d6673ea0e5c1dea6d5d016880e64f6
Doc: update Python 'gpu' module reference
- add missing uniforms.
- add uniform types.
- link to RNA equivalent.
- remove 'value' from uniforms (they were wrong, better use module members anyway).
- various corrections & edits.
Fixes T45505
===================================================================
M doc/python_api/rst/gpu.rst
===================================================================
diff --git a/doc/python_api/rst/gpu.rst b/doc/python_api/rst/gpu.rst
index aaceb3c..b56523c 100644
--- a/doc/python_api/rst/gpu.rst
+++ b/doc/python_api/rst/gpu.rst
@@ -16,24 +16,24 @@ 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).
+ 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
+GLSL Data Type
--------------
.. _data-type:
Type of GLSL data.
-For shader uniforms, the data type determines which glUniform function
+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
+For vertex attributes, the data type determines which ``glVertexAttrib`` function
variant to use to send the vertex attribute to the GPU.
See export_shader_
@@ -42,53 +42,37 @@ See export_shader_
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
------------------
+GLSL Uniform Types
+------------------
.. _uniform-type:
@@ -101,7 +85,7 @@ The calculation of some of the uniforms is based on matrices available in the sc
.. _mat4_cam_to_world:
.. _mat4_world_to_cam:
- *mat4_cam_to_world*
+ ``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.
@@ -112,7 +96,7 @@ The calculation of some of the uniforms is based on matrices available in the sc
.. _mat4_object_to_world:
.. _mat4_world_to_object:
- *mat4_object_to_world*
+ ``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.
@@ -122,7 +106,7 @@ The calculation of some of the uniforms is based on matrices available in the sc
.. _mat4_lamp_to_world:
.. _mat4_world_to_lamp:
- *mat4_lamp_to_world*
+ ``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.
@@ -130,151 +114,299 @@ The calculation of some of the uniforms is based on matrices available in the sc
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.
+
.. 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.
+ A matrix that converts world coordinates to camera coordinates (see mat4_world_to_cam_).
- :value: 1
+ :type: matrix4x4
.. 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.
+ A matrix that converts object coordinates to world coordinates (see mat4_object_to_world_).
- :value: 2
+ :type: matrix4x4
.. 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
+ :type: matrix4x4
.. 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
+ :type: matrix4x4
.. 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.
+ An RGB color + alpha defined at object level.
+ Each values between 0.0 and 1.0.
- :value: 5
+ See :class:`bpy.types.Object.color`.
+
+ :type: float4
+
+.. data:: GPU_DYNAMIC_OBJECT_AUTOBUMPSCALE
+
+ Multiplier for bump-map scaling.
+
+ :type: float
-.. 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
+GLSL Lamp Uniforms
+^^^^^^^^^^^^^^^^^^
- mat4_world_to_cam_ * (-vec3_lamp_Z_axis)
+.. note::
- 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_DYNVEC
-.. data:: GPU_DYNAMIC_LAMP_DYNCO
+ Represents the direction of light in camera space.
- The uniform is a vector of 3 float representing the position of the light in camera space.
- Computed as
+ Computed as:
+ mat4_world_to_cam_ * (-vec3_lamp_Z_axis)
- mat4_world_to_cam_ * vec3_lamp_pos
+ .. note::
+ - The lamp Z axis points to the opposite direction of light.
+ - The norm of the vector should be unit length.
- Can be set once per frame.
- There is one uniform of that type per lamp lighting the material.
+ :type: float3
- :value: 7
+.. data:: GPU_DYNAMIC_LAMP_DYNCO
-.. data:: GPU_DYNAMIC_LAMP_DYNIMAT
+ Represents the position of the light in camera space.
- The uniform is a 4x4 GL matrix that converts vector in camera space to lamp space.
- Computed as
+ Computed as:
+ mat4_world_to_cam_ * vec3_lamp_pos
- mat4_world_to_lamp_ * mat4_cam_to_world_
+ :type: float3
- Can be set once per frame.
- There is one uniform of that type per lamp lighting the material.
+.. data:: GPU_DYNAMIC_LAMP_DYNIMAT
- :value: 8
+ Matrix that converts vector in camera space to lamp space.
+
+ Computed as:
+ mat4_world_to_lamp_ * mat4_cam_to_world_
+
+ :type: matrix4x4
.. 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
+ Matrix that converts a vector in camera space to shadow buffer depth space.
- mat4_perspective_to_depth_ * mat4_lamp_to_perspective_ * mat4_world_to_lamp_ * mat4_cam_to_world_.
+ 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::
+ ``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.
+ .. note::
- :value: 9
+ - There is one uniform of that type per lamp casting shadow in the scene.
+
+ :type: matrix4x4
.. 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.
+ See :class:`bpy.types.Lamp.energy`.
- :value: 10
+ :type: float
.. 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.
+ See :class:`bpy.types.Lamp.color`.
+
+ :type: float3
+
+.. data:: GPU_DYNAMIC_LAMP_DISTANCE
+
+ See :class:`bpy.types.Lamp.distance`.
+
+ :type: float
+
+.. data:: GPU_DYNAMIC_LAMP_ATT1
+
+ See
+ :class:`bpy.types.PointLamp.linear_attenuation`,
+ :class:`bpy.types.SpotLamp.linear_attenuation`.
+
+ :type: float
+
+.. data:: GPU_DYNAMIC_LAMP_ATT2
+
+ See
+ :class:`bpy.types.PointLamp.quadratic_attenuation`,
+ :class:`bpy.types.SpotLamp.quadratic_attenuation`.
- :value: 11
+ :type: float
+
+.. data:: GPU_DYNAMIC_LAMP_SPOTSIZE
+
+ See :class:`bpy.types.SpotLamp.spot_size`.
+
+ :type: float
+
+.. data:: GPU_DYNAMIC_LAMP_SPOTBLEND
+
+ See :class:`bpy.types.SpotLamp.spot_blend`.
+
+ :type: float
+
+
+GLSL Sampler Uniforms
+^^^^^^^^^^^^^^^^^^^^^
.. data:: GPU_DYNAMIC_SAMPLER_2DBUFFER
- The uniform is an integer representing an internal texture used for certain effect
+ Represents an internal texture used for certain effect
(color band, etc).
- :value: 12
+ :type: integer
.. data:: GPU_DYNAMIC_SAMPLER_2DIMAGE
- The uniform is an integer representing a texture loaded f
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list