01e5a7cd387376987a45cb05daa32dbdf469227b
[blender.git] / source / gameengine / PyDoc / bge.render.rst
1
2 Game Engine bge.render Module
3 =============================
4
5 .. module:: bge.render
6
7 .. code-block:: python
8
9    # Example Uses an L{SCA_MouseSensor}, and two L{KX_ObjectActuator}s to implement MouseLook::
10    # To use a mouse movement sensor "Mouse" and a 
11    # motion actuator to mouse look:
12    import bge.render
13    import bge.logic
14
15    # SCALE sets the speed of motion
16    SCALE=[1, 0.5]
17    
18    co = bge.logic.getCurrentController()
19    obj = co.getOwner()
20    mouse = co.getSensor("Mouse")
21    lmotion = co.getActuator("LMove")
22    wmotion = co.getActuator("WMove")
23    
24    # Transform the mouse coordinates to see how far the mouse has moved.
25    def mousePos():
26       x = (bge.render.getWindowWidth()/2 - mouse.getXPosition())*SCALE[0]
27       y = (bge.render.getWindowHeight()/2 - mouse.getYPosition())*SCALE[1]
28       return (x, y)
29    
30    pos = mousePos()
31    
32    # Set the amount of motion: X is applied in world coordinates...
33    lmotion.setTorque(0.0, 0.0, pos[0], False)
34    # ...Y is applied in local coordinates
35    wmotion.setTorque(-pos[1], 0.0, 0.0, True)
36    
37    # Activate both actuators
38    bge.logic.addActiveActuator(lmotion, True)
39    bge.logic.addActiveActuator(wmotion, True)
40    
41    # Centre the mouse
42    bge.render.setMousePosition(bge.render.getWindowWidth()/2, bge.render.getWindowHeight()/2)
43
44
45 .. data:: KX_TEXFACE_MATERIAL
46
47    Materials as defined by the texture face settings.
48
49 .. data:: KX_BLENDER_MULTITEX_MATERIAL
50
51    Materials approximating blender materials with multitexturing.
52
53 .. data:: KX_BLENDER_GLSL_MATERIAL
54
55    Materials approximating blender materials with GLSL.
56
57 .. function:: getWindowWidth()
58
59    Gets the width of the window (in pixels)
60    
61    :rtype: integer
62
63 .. function:: getWindowHeight()
64
65    Gets the height of the window (in pixels)
66    
67    :rtype: integer
68
69 .. function:: makeScreenshot(filename)
70
71    Writes a screenshot to the given filename.
72    
73    If filename starts with // the image will be saved relative to the current directory.
74    If the filename contains # it will be replaced with the frame number.
75    
76    The standalone player saves .png files. It does not support colour space conversion 
77    or gamma correction.
78    
79    When run from Blender, makeScreenshot supports Iris, IrisZ, TGA, Raw TGA, PNG, HamX, and Jpeg.
80    Gamma, Colourspace conversion and Jpeg compression are taken from the Render settings panels.
81    
82    :type filename: string
83
84
85 .. function:: enableVisibility(visible)
86
87    Doesn't really do anything...
88
89
90 .. function:: showMouse(visible)
91
92    Enables or disables the operating system mouse cursor.
93    
94    :type visible: boolean
95
96
97 .. function:: setMousePosition(x, y)
98
99    Sets the mouse cursor position.
100    
101    :type x: integer
102    :type y: integer
103
104
105 .. function:: setBackgroundColor(rgba)
106
107    Sets the window background colour.
108    
109    :type rgba: list [r, g, b, a]
110
111
112 .. function:: setMistColor(rgb)
113
114    Sets the mist colour.
115    
116    :type rgb: list [r, g, b]
117
118    
119 .. function:: setAmbientColor(rgb)
120
121    Sets the color of ambient light.
122    
123    :type rgb: list [r, g, b]
124
125
126 .. function:: setMistStart(start)
127
128    Sets the mist start value.  Objects further away than start will have mist applied to them.
129    
130    :type start: float
131
132
133 .. function:: setMistEnd(end)
134
135    Sets the mist end value.  Objects further away from this will be coloured solid with
136    the colour set by setMistColor().
137    
138    :type end: float
139
140    
141 .. function:: disableMist()
142
143    Disables mist.
144    
145    .. note:: Set any of the mist properties to enable mist.
146
147    
148 .. function:: setEyeSeparation(eyesep)
149
150    Sets the eye separation for stereo mode. Usually Focal Length/30 provides a confortable value.
151    
152    :arg eyesep: The distance between the left and right eye.
153    :type eyesep: float
154
155
156 .. function:: getEyeSeparation()
157
158    Gets the current eye separation for stereo mode.
159    
160    :rtype: float
161
162    
163 .. function:: setFocalLength(focallength)
164
165    Sets the focal length for stereo mode. It uses the current camera focal length as initial value.
166    
167    :arg focallength: The focal length.  
168    :type focallength: float
169
170 .. function:: getFocalLength()
171
172    Gets the current focal length for stereo mode.
173    
174    :rtype: float
175
176 .. function:: setMaterialMode(mode)
177
178    Set the material mode to use for OpenGL rendering.
179    
180    :type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
181
182    .. note:: Changes will only affect newly created scenes.
183
184
185 .. function:: getMaterialMode(mode)
186
187    Get the material mode to use for OpenGL rendering.
188    
189    :rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
190
191
192 .. function:: setGLSLMaterialSetting(setting, enable)
193
194    Enables or disables a GLSL material setting.
195    
196    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
197    :type enable: boolean
198
199
200 .. function:: getGLSLMaterialSetting(setting, enable)
201
202    Get the state of a GLSL material setting.
203    
204    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
205    :rtype: boolean
206
207
208 .. function:: drawLine(fromVec,toVec,color)
209
210    Draw a line in the 3D scene.
211    
212    :arg fromVec: the origin of the line
213    :type fromVec: list [x, y, z]
214    :arg toVec: the end of the line
215    :type toVec: list [x, y, z]
216    :arg color: the color of the line
217    :type color: list [r, g, b]
218
219
220 .. function:: enableMotionBlur(factor)
221
222    Enable the motion blue effect.
223    
224    :arg factor: the ammount of motion blur to display.
225    :type factor: float [0.0 - 1.0]
226
227
228 .. function:: disableMotionBlur()
229
230    Disable the motion blue effect.
231