Docs: touch ups in the bge.render doc introduction
[blender.git] / doc / python_api / rst / bge.render.rst
1
2 Rasterizer (bge.render)
3 =======================
4
5 *****
6 Intro
7 *****
8
9 .. module:: bge.render
10
11 Example of using a :class:`bge.types.SCA_MouseSensor`, and two :class:`bge.types.KX_ObjectActuator` to implement MouseLook:
12
13 .. note::
14    This can also be achieved with the :class:`bge.types.KX_MouseActuator`.
15
16 .. code-block:: python
17
18    # To use a mouse movement sensor "Mouse" and a
19    # motion actuator to mouse look:
20    import bge
21
22    # scale sets the speed of motion
23    scale = 1.0, 0.5
24
25    co = bge.logic.getCurrentController()
26    obj = co.owner
27    mouse = co.sensors["Mouse"]
28    lmotion = co.actuators["LMove"]
29    wmotion = co.actuators["WMove"]
30
31    # Transform the mouse coordinates to see how far the mouse has moved.
32    def mousePos():
33       x = (bge.render.getWindowWidth() / 2 - mouse.position[0]) * scale[0]
34       y = (bge.render.getWindowHeight() / 2 - mouse.position[1]) * scale[1]
35       return (x, y)
36
37    pos = mousePos()
38
39    # Set the amount of motion: X is applied in world coordinates...
40    wmotion.useLocalTorque = False
41    wmotion.torque = ((0.0, 0.0, pos[0]))
42
43    # ...Y is applied in local coordinates
44    lmotion.useLocalTorque = True
45    lmotion.torque = ((-pos[1], 0.0, 0.0))
46
47    # Activate both actuators
48    co.activate(lmotion)
49    co.activate(wmotion)
50
51    # Centre the mouse
52    bge.render.setMousePosition(int(bge.render.getWindowWidth() / 2), int(bge.render.getWindowHeight() / 2))
53
54 *********
55 Constants
56 *********
57
58 .. data:: KX_TEXFACE_MATERIAL
59
60    Materials as defined by the texture face settings.
61
62 .. data:: KX_BLENDER_MULTITEX_MATERIAL
63
64    Materials approximating blender materials with multitexturing.
65
66 .. data:: KX_BLENDER_GLSL_MATERIAL
67
68    Materials approximating blender materials with GLSL.
69    
70 .. DATA:: VSYNC_OFF
71
72    Disables vsync
73
74 .. DATA:: VSYNC_ON
75
76    Enables vsync
77
78 .. DATA:: VSYNC_ADAPTIVE
79
80    Enables adaptive vsync if supported. Adaptive vsync enables vsync if the framerate is above the monitors refresh rate. Otherwise, vsync is diabled if the framerate is too low.
81
82 .. data:: LEFT_EYE
83
84    Left eye being used during stereoscopic rendering.
85
86 .. data:: RIGHT_EYE
87
88    Right eye being used during stereoscopic rendering.
89
90 *********
91 Functions
92 *********
93
94 .. function:: getWindowWidth()
95
96    Gets the width of the window (in pixels)
97    
98    :rtype: integer
99
100 .. function:: getWindowHeight()
101
102    Gets the height of the window (in pixels)
103    
104    :rtype: integer
105
106 .. function:: setWindowSize(width, height)
107
108    Set the width and height of the window (in pixels). This also works for fullscreen applications.
109    
110    :type width: integer
111    :type height: integer
112
113 .. function:: setFullScreen(enable)
114
115    Set whether or not the window should be fullscreen.
116    
117    :type enable: bool
118
119 .. function:: getFullScreen()
120
121    Returns whether or not the window is fullscreen.
122    
123    :rtype: bool
124
125 .. function:: makeScreenshot(filename)
126
127    Writes a screenshot to the given filename.
128    
129    If filename starts with // the image will be saved relative to the current directory.
130    If the filename contains # it will be replaced with the frame number.
131    
132    The standalone player saves .png files. It does not support color space conversion 
133    or gamma correction.
134    
135    When run from Blender, makeScreenshot supports all Blender image file formats like PNG, TGA, Jpeg and OpenEXR.
136    Gamma, Colorspace conversion and Jpeg compression are taken from the Render settings panels.
137    
138    :type filename: string
139
140
141 .. function:: enableVisibility(visible)
142
143    Doesn't really do anything...
144
145
146 .. function:: showMouse(visible)
147
148    Enables or disables the operating system mouse cursor.
149    
150    :type visible: boolean
151
152
153 .. function:: setMousePosition(x, y)
154
155    Sets the mouse cursor position.
156    
157    :type x: integer
158    :type y: integer
159
160
161 .. function:: setBackgroundColor(rgba)
162
163    Sets the window background color.
164    
165    :type rgba: list [r, g, b, a]
166
167
168 .. function:: setMistColor(rgb)
169
170    Sets the mist color.
171    
172    :type rgb: list [r, g, b]
173
174    
175 .. function:: setAmbientColor(rgb)
176
177    Sets the color of ambient light.
178    
179    :type rgb: list [r, g, b]
180
181
182 .. function:: setMistStart(start)
183
184    Sets the mist start value.  Objects further away than start will have mist applied to them.
185    
186    :type start: float
187
188
189 .. function:: setMistEnd(end)
190
191    Sets the mist end value.  Objects further away from this will be colored solid with
192    the color set by setMistColor().
193    
194    :type end: float
195
196    
197 .. function:: disableMist()
198
199    Disables mist.
200    
201    .. note:: Set any of the mist properties to enable mist.
202
203    
204 .. function:: setEyeSeparation(eyesep)
205
206    Sets the eye separation for stereo mode. Usually Focal Length/30 provides a confortable value.
207    
208    :arg eyesep: The distance between the left and right eye.
209    :type eyesep: float
210
211
212 .. function:: getEyeSeparation()
213
214    Gets the current eye separation for stereo mode.
215    
216    :rtype: float
217
218    
219 .. function:: setFocalLength(focallength)
220
221    Sets the focal length for stereo mode. It uses the current camera focal length as initial value.
222    
223    :arg focallength: The focal length.  
224    :type focallength: float
225
226 .. function:: getFocalLength()
227
228    Gets the current focal length for stereo mode.
229    
230    :rtype: float
231
232 .. function:: getStereoEye()
233
234    Gets the current stereoscopy eye being rendered.
235    This function is mainly used in a :class:`bge.types.KX_Scene.pre_draw` callback
236    function to customize the camera projection matrices for each
237    stereoscopic eye.
238
239    :rtype: LEFT_EYE, RIGHT_EYE
240
241 .. function:: setMaterialMode(mode)
242
243    Set the material mode to use for OpenGL rendering.
244    
245    :type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
246
247    .. note:: Changes will only affect newly created scenes.
248
249
250 .. function:: getMaterialMode(mode)
251
252    Get the material mode to use for OpenGL rendering.
253    
254    :rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
255
256
257 .. function:: setGLSLMaterialSetting(setting, enable)
258
259    Enables or disables a GLSL material setting.
260    
261    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
262    :type enable: boolean
263
264
265 .. function:: getGLSLMaterialSetting(setting, enable)
266
267    Get the state of a GLSL material setting.
268    
269    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
270    :rtype: boolean
271
272 .. function:: setAnisotropicFiltering(level)
273
274    Set the anisotropic filtering level for textures.
275    
276    :arg level: The new anisotropic filtering level to use
277    :type level: integer (must be one of 1, 2, 4, 8, 16)
278    
279    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
280    
281 .. function:: getAnisotropicFiltering()
282
283    Get the anisotropic filtering level used for textures.
284    
285    :rtype: integer (one of 1, 2, 4, 8, 16)
286
287 .. function:: setMipmapping(value)
288
289    Change how to use mipmapping.
290    
291    :type value: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
292    
293    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
294
295 .. function:: getMipmapping()
296
297    Get the current mipmapping setting.
298    
299    :rtype: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
300    
301 .. function:: drawLine(fromVec,toVec,color)
302
303    Draw a line in the 3D scene.
304    
305    :arg fromVec: the origin of the line
306    :type fromVec: list [x, y, z]
307    :arg toVec: the end of the line
308    :type toVec: list [x, y, z]
309    :arg color: the color of the line
310    :type color: list [r, g, b]
311
312
313 .. function:: enableMotionBlur(factor)
314
315    Enable the motion blur effect.
316    
317    :arg factor: the ammount of motion blur to display.
318    :type factor: float [0.0 - 1.0]
319
320
321 .. function:: disableMotionBlur()
322
323    Disable the motion blur effect.
324
325 .. function:: showFramerate(enable)
326
327    Show or hide the framerate.
328
329    :type enable: boolean
330
331 .. function:: showProfile(enable)
332
333    Show or hide the profile.
334
335    :type enable: boolean
336
337 .. function:: showProperties(enable)
338
339    Show or hide the debug properties.
340
341    :type enable: boolean
342
343 .. function:: autoDebugList(enable)
344
345    Enable or disable auto adding debug properties to the debug list.
346
347    :type enable: boolean
348
349 .. function:: clearDebugList()
350
351    Clears the debug property list.
352
353 .. function:: setVsync(value)
354
355    Set the vsync value
356
357    :arg value: One of VSYNC_OFF, VSYNC_ON, VSYNC_ADAPTIVE
358    :type value: integer
359
360 .. function:: getVsync()
361
362    Get the current vsync value
363
364    :rtype: One of VSYNC_OFF, VSYNC_ON, VSYNC_ADAPTIVE