3abbd50a4535b2143df23ac5b72d0412a363fbd8
[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:: Deprecated use setUseMist().
202
203    
204 .. function:: setUseMist(enable)
205
206    Disable or enable the mist.
207
208    :type enable: boolean
209
210
211 .. function:: setEyeSeparation(eyesep)
212
213    Sets the eye separation for stereo mode. Usually Focal Length/30 provides a confortable value.
214    
215    :arg eyesep: The distance between the left and right eye.
216    :type eyesep: float
217
218
219 .. function:: getEyeSeparation()
220
221    Gets the current eye separation for stereo mode.
222    
223    :rtype: float
224
225    
226 .. function:: setFocalLength(focallength)
227
228    Sets the focal length for stereo mode. It uses the current camera focal length as initial value.
229    
230    :arg focallength: The focal length.  
231    :type focallength: float
232
233 .. function:: getFocalLength()
234
235    Gets the current focal length for stereo mode.
236    
237    :rtype: float
238
239 .. function:: getStereoEye()
240
241    Gets the current stereoscopy eye being rendered.
242    This function is mainly used in a :class:`bge.types.KX_Scene.pre_draw` callback
243    function to customize the camera projection matrices for each
244    stereoscopic eye.
245
246    :rtype: LEFT_EYE, RIGHT_EYE
247
248 .. function:: setMaterialMode(mode)
249
250    Set the material mode to use for OpenGL rendering.
251    
252    :type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
253
254    .. note:: Changes will only affect newly created scenes.
255
256
257 .. function:: getMaterialMode(mode)
258
259    Get the material mode to use for OpenGL rendering.
260    
261    :rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
262
263
264 .. function:: setGLSLMaterialSetting(setting, enable)
265
266    Enables or disables a GLSL material setting.
267    
268    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
269    :type enable: boolean
270
271
272 .. function:: getGLSLMaterialSetting(setting, enable)
273
274    Get the state of a GLSL material setting.
275    
276    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
277    :rtype: boolean
278
279 .. function:: setAnisotropicFiltering(level)
280
281    Set the anisotropic filtering level for textures.
282    
283    :arg level: The new anisotropic filtering level to use
284    :type level: integer (must be one of 1, 2, 4, 8, 16)
285    
286    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
287    
288 .. function:: getAnisotropicFiltering()
289
290    Get the anisotropic filtering level used for textures.
291    
292    :rtype: integer (one of 1, 2, 4, 8, 16)
293
294 .. function:: setMipmapping(value)
295
296    Change how to use mipmapping.
297    
298    :type value: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
299    
300    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
301
302 .. function:: getMipmapping()
303
304    Get the current mipmapping setting.
305    
306    :rtype: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
307    
308 .. function:: drawLine(fromVec,toVec,color)
309
310    Draw a line in the 3D scene.
311    
312    :arg fromVec: the origin of the line
313    :type fromVec: list [x, y, z]
314    :arg toVec: the end of the line
315    :type toVec: list [x, y, z]
316    :arg color: the color of the line
317    :type color: list [r, g, b]
318
319
320 .. function:: enableMotionBlur(factor)
321
322    Enable the motion blur effect.
323    
324    :arg factor: the ammount of motion blur to display.
325    :type factor: float [0.0 - 1.0]
326
327
328 .. function:: disableMotionBlur()
329
330    Disable the motion blur effect.
331
332 .. function:: showFramerate(enable)
333
334    Show or hide the framerate.
335
336    :type enable: boolean
337
338 .. function:: showProfile(enable)
339
340    Show or hide the profile.
341
342    :type enable: boolean
343
344 .. function:: showProperties(enable)
345
346    Show or hide the debug properties.
347
348    :type enable: boolean
349
350 .. function:: autoDebugList(enable)
351
352    Enable or disable auto adding debug properties to the debug list.
353
354    :type enable: boolean
355
356 .. function:: clearDebugList()
357
358    Clears the debug property list.
359
360 .. function:: setVsync(value)
361
362    Set the vsync value
363
364    :arg value: One of VSYNC_OFF, VSYNC_ON, VSYNC_ADAPTIVE
365    :type value: integer
366
367 .. function:: getVsync()
368
369    Get the current vsync value
370
371    :rtype: One of VSYNC_OFF, VSYNC_ON, VSYNC_ADAPTIVE