Cr8-xyz/blender
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Style cleanup of gpu rst file.

Browse Source
This commit is contained in:
Campbell Barton
2012-02-09 06:38:54 +00:00
parent 33bca3075f
commit fd60de606a
1 changed files with 301 additions and 299 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
doc/python_api/rst/gpu.rst
View File

@@ -1,13 +1,14 @@
*******************
GPU functions (gpu)
===================
*******************
.. module:: gpu
This module provides access to materials GLSL shaders.
*****
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
@@ -20,11 +21,10 @@ and in the game engine.
is modified (e.g. new uniform type).
*********
Constants
*********
=========
--------------
GLSL data type
--------------
@@ -86,7 +86,7 @@ See export_shader_
:value: 8
-----------------
GLSL uniform type
-----------------
@@ -267,7 +267,7 @@ The calculation of some of the uniforms is based on matrices available in the sc
:value: 14
-------------------
GLSL attribute type
-------------------
@@ -285,7 +285,7 @@ layer that contains the vertex attribute.
.. code-block:: python
mesh.uv_textures[attribute['name']]
mesh.uv_textures[attribute["name"]]
:value: 5
@@ -298,7 +298,7 @@ layer that contains the vertex attribute.
.. code-block:: python
mesh.vertex_colors[attribute['name']]
mesh.vertex_colors[attribute["name"]]
:value: 6
@@ -326,9 +326,9 @@ layer that contains the vertex attribute.
:value: 18
*********
Functions
*********
=========
.. _export_shader:
@@ -348,20 +348,20 @@ Functions
The dictionary contains the following elements:
* ['fragment'] : string
* ["fragment"] : string
fragment shader source code.
* ['vertex'] : string
* ["vertex"] : string
vertex shader source code.
* ['uniforms'] : sequence
* ["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
* ["varname"] : string
name of the uniform in the fragment shader. Always of the form 'unf<number>'.
* ['datatype'] : integer
* ["datatype"] : integer
data type of the uniform variable. Can be one of the following:
* :data:`gpu.GPU_DATA_1I` : use glUniform1i
@@ -372,11 +372,11 @@ Functions
* :data:`gpu.GPU_DATA_9F` : use glUniformMatrix3fv
* :data:`gpu.GPU_DATA_16F` : use glUniformMatrix4fv
* ['type'] : integer
* ["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'] : :class:`bpy.types.Object`
* ["lamp"] : :class:`bpy.types.Object`
Reference to the lamp object from which the uniforms value are extracted. Set for the following uniforms types:
.. hlist::
@@ -397,7 +397,7 @@ Functions
.. code-block:: python
obmat = uniform['lamp'].matrix_world
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].
@@ -406,7 +406,7 @@ Functions
.. code-block:: python
la = uniform['lamp'].data
la = uniform["lamp"].data
from which you get la.energy and la.color
@@ -416,17 +416,17 @@ Functions
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'] : :class:`bpy.types.Image`
* ["image"] : :class:`bpy.types.Image`
Reference to the image databloc. Set for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE`. You can get the image data from:
.. code-block:: python
# full path to image file
uniform['image'].filepath
uniform["image"].filepath
# image size as a 2-dimensional array of int
uniform['image'].size
uniform["image"].size
* ['texnumber'] : integer
* ["texnumber"] : integer
Channel number to which the texture is bound when drawing the object.
Set for uniform types :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`, :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE` and :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`.
@@ -434,29 +434,29 @@ Functions
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
* ["texpixels"] : byte array
texture data for uniform type :data:`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.
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
* ["texsize"] : integer
horizontal size of texture for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`.
The texture data is in ['texpixels'].
The texture data is in ["texpixels"].
* ['attributes'] : sequence
* ["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
* ["varname"] : string
name of the uniform in the vertex shader. Always of the form 'att<number>'.
* ['datatype'] : integer
* ["datatype"] : integer
data type of vertex attribute, can be one of the following:
* :data:`gpu.GPU_DATA_2F` : use glVertexAttrib2fv
@@ -464,7 +464,7 @@ Functions
* :data:`gpu.GPU_DATA_4F` : use glVertexAttrib4fv
* :data:`gpu.GPU_DATA_4UB` : use glVertexAttrib4ubv
* ['number'] : integer
* ["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
@@ -475,11 +475,11 @@ Functions
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"] : integer
type of the mesh custom data from which the vertex attribute is loaded.
See attribute-type_.
* ['name'] : string or integer
* ["name"] : string or integer
custom data layer name, used for attribute type :data:`gpu.CD_MTFACE` and :data:`gpu.CD_MCOL`.
Example:
@@ -488,21 +488,21 @@ Functions
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']
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))
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']))
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
*****
=====
.. _mat4_lamp_to_perspective:
@@ -511,20 +511,22 @@ Notes
The following pseudo code shows how the *mat4_lamp_to_perspective* matrix is computed
in blender for uniforms of :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` type::
#Get the lamp datablock with:
lamp=bpy.data.objects[uniform['lamp']].data
.. code-block:: python
#Compute the projection matrix:
#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:
# 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)
mat4_lamp_to_perspective = glFrustum(-wsize, wsize, -wsize, wsize, lamp.clista, lamp.clipend)
2. Creation of the shadow map for a spot lamp.