BGE: Add new world API KX_WorldInfo (KX_Scene)
[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 .. data:: KX_MIST_QUADRATIC
91
92    Type of quadratic attenuation used to fade mist. (Deprecated: use KX_WorldInfo.KX_MIST_QUADRATIC)
93
94 .. data:: KX_MIST_LINEAR
95
96    Type of linear attenuation used to fade mist. (Deprecated: use KX_WorldInfo.KX_MIST_LINEAR)
97
98 .. data:: KX_MIST_INV_QUADRATIC
99
100    Type of inverse quadratic attenuation used to fade mist. (Deprecated: use KX_WorldInfo.KX_MIST_INV_QUADRATIC)
101
102
103 *********
104 Functions
105 *********
106
107 .. function:: getWindowWidth()
108
109    Gets the width of the window (in pixels)
110    
111    :rtype: integer
112
113 .. function:: getWindowHeight()
114
115    Gets the height of the window (in pixels)
116    
117    :rtype: integer
118
119 .. function:: setWindowSize(width, height)
120
121    Set the width and height of the window (in pixels). This also works for fullscreen applications.
122    
123    :type width: integer
124    :type height: integer
125
126 .. function:: setFullScreen(enable)
127
128    Set whether or not the window should be fullscreen.
129    
130    :type enable: bool
131
132 .. function:: getFullScreen()
133
134    Returns whether or not the window is fullscreen.
135    
136    :rtype: bool
137
138 .. function:: makeScreenshot(filename)
139
140    Writes a screenshot to the given filename.
141    
142    If filename starts with // the image will be saved relative to the current directory.
143    If the filename contains # it will be replaced with the frame number.
144    
145    The standalone player saves .png files. It does not support color space conversion 
146    or gamma correction.
147    
148    When run from Blender, makeScreenshot supports all Blender image file formats like PNG, TGA, Jpeg and OpenEXR.
149    Gamma, Colorspace conversion and Jpeg compression are taken from the Render settings panels.
150    
151    :type filename: string
152
153
154 .. function:: enableVisibility(visible)
155
156    Doesn't really do anything...
157
158
159 .. function:: showMouse(visible)
160
161    Enables or disables the operating system mouse cursor.
162    
163    :type visible: boolean
164
165
166 .. function:: setMousePosition(x, y)
167
168    Sets the mouse cursor position.
169    
170    :type x: integer
171    :type y: integer
172
173
174 .. function:: setBackgroundColor(rgba)
175
176    Sets the window background color. (Deprecated: use KX_WorldInfo.background_color)
177
178    :type rgba: list [r, g, b, a]
179
180
181 .. function:: setAmbientColor(rgb)
182
183    Sets the color of ambient light. (Deprecated: use KX_WorldInfo.ambient_color)
184
185    :type rgb: list [r, g, b]
186
187
188 .. function:: setMistColor(rgb)
189
190    Sets the mist color. (Deprecated: use KX_WorldInfo.mist_color)
191
192    :type rgb: list [r, g, b]
193
194
195 .. function:: setMistType(mode)
196
197    Sets the mist attenuation type. (Deprecated: use KX_WorldInfo.mist_type)
198
199    :type mode: KX_MIST_QUADRATIC, KX_MIST_LINEAR, KX_MIST_INV_QUADRATIC
200
201
202 .. function:: setMistStart(start)
203
204    Sets the mist start value. Objects further away than start will have mist applied to them.
205    (Deprecated: use KX_WorldInfo.mist_start)
206
207    :type start: float
208
209
210 .. function:: setMistEnd(end)
211
212    Sets the mist end value.  Objects further away from this will be colored solid with
213    the color set by setMistColor(). (Deprecated: use KX_WorldInfo.mist_distance)
214
215    :type end: float
216
217
218 .. function:: setMistIntensity(intensity)
219
220    Sets the mist intensity value. (Deprecated: use KX_WorldInfo.mist_intensity)
221
222    :type start: float
223
224 .. function:: disableMist()
225
226
227    Disables mist.
228    
229    .. note:: Deprecated: use KX_WorldInfo.mist_enable.
230
231    
232 .. function:: setUseMist(enable)
233
234    Disable or enable the mist. (Deprecated: use KX_WorldInfo.mist_enable)
235
236    :type enable: boolean
237
238
239 .. function:: setEyeSeparation(eyesep)
240
241    Sets the eye separation for stereo mode. Usually Focal Length/30 provides a confortable value.
242    
243    :arg eyesep: The distance between the left and right eye.
244    :type eyesep: float
245
246
247 .. function:: getEyeSeparation()
248
249    Gets the current eye separation for stereo mode.
250    
251    :rtype: float
252
253    
254 .. function:: setFocalLength(focallength)
255
256    Sets the focal length for stereo mode. It uses the current camera focal length as initial value.
257    
258    :arg focallength: The focal length.  
259    :type focallength: float
260
261 .. function:: getFocalLength()
262
263    Gets the current focal length for stereo mode.
264    
265    :rtype: float
266
267 .. function:: getStereoEye()
268
269    Gets the current stereoscopy eye being rendered.
270    This function is mainly used in a :class:`bge.types.KX_Scene.pre_draw` callback
271    function to customize the camera projection matrices for each
272    stereoscopic eye.
273
274    :rtype: LEFT_EYE, RIGHT_EYE
275
276 .. function:: setMaterialMode(mode)
277
278    Set the material mode to use for OpenGL rendering.
279    
280    :type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
281
282    .. note:: Changes will only affect newly created scenes.
283
284
285 .. function:: getMaterialMode(mode)
286
287    Get the material mode to use for OpenGL rendering.
288    
289    :rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
290
291
292 .. function:: setGLSLMaterialSetting(setting, enable)
293
294    Enables or disables a GLSL material setting.
295    
296    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
297    :type enable: boolean
298
299
300 .. function:: getGLSLMaterialSetting(setting, enable)
301
302    Get the state of a GLSL material setting.
303    
304    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
305    :rtype: boolean
306
307 .. function:: setAnisotropicFiltering(level)
308
309    Set the anisotropic filtering level for textures.
310    
311    :arg level: The new anisotropic filtering level to use
312    :type level: integer (must be one of 1, 2, 4, 8, 16)
313    
314    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
315    
316 .. function:: getAnisotropicFiltering()
317
318    Get the anisotropic filtering level used for textures.
319    
320    :rtype: integer (one of 1, 2, 4, 8, 16)
321
322 .. function:: setMipmapping(value)
323
324    Change how to use mipmapping.
325    
326    :type value: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
327    
328    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
329
330 .. function:: getMipmapping()
331
332    Get the current mipmapping setting.
333    
334    :rtype: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
335    
336 .. function:: drawLine(fromVec,toVec,color)
337
338    Draw a line in the 3D scene.
339    
340    :arg fromVec: the origin of the line
341    :type fromVec: list [x, y, z]
342    :arg toVec: the end of the line
343    :type toVec: list [x, y, z]
344    :arg color: the color of the line
345    :type color: list [r, g, b]
346
347
348 .. function:: enableMotionBlur(factor)
349
350    Enable the motion blur effect.
351    
352    :arg factor: the ammount of motion blur to display.
353    :type factor: float [0.0 - 1.0]
354
355
356 .. function:: disableMotionBlur()
357
358    Disable the motion blur effect.
359
360 .. function:: showFramerate(enable)
361
362    Show or hide the framerate.
363
364    :type enable: boolean
365
366 .. function:: showProfile(enable)
367
368    Show or hide the profile.
369
370    :type enable: boolean
371
372 .. function:: showProperties(enable)
373
374    Show or hide the debug properties.
375
376    :type enable: boolean
377
378 .. function:: autoDebugList(enable)
379
380    Enable or disable auto adding debug properties to the debug list.
381
382    :type enable: boolean
383
384 .. function:: clearDebugList()
385
386    Clears the debug property list.
387
388 .. function:: setVsync(value)
389
390    Set the vsync value
391
392    :arg value: One of VSYNC_OFF, VSYNC_ON, VSYNC_ADAPTIVE
393    :type value: integer
394
395 .. function:: getVsync()
396
397    Get the current vsync value
398
399    :rtype: One of VSYNC_OFF, VSYNC_ON, VSYNC_ADAPTIVE