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