BGE: Add setMistType and setMistIntensity API.
[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.
93
94 .. data:: KX_MIST_LINEAR
95
96    Type of linear attenuation used to fade mist.
97
98 .. data:: KX_MIST_INV_QUADRATIC
99
100    Type of inverse quadratic attenuation used to fade mist.
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.
177    
178    :type rgba: list [r, g, b, a]
179
180
181 .. function:: setAmbientColor(rgb)
182
183    Sets the color of ambient light.
184    
185    :type rgb: list [r, g, b]
186
187
188 .. function:: setMistColor(rgb)
189
190    Sets the mist color.
191    
192    :type rgb: list [r, g, b]
193
194
195 .. function:: setMistType(mode)
196
197    Sets the mist attenuation 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    
206    :type start: float
207
208
209 .. function:: setMistEnd(end)
210
211    Sets the mist end value.  Objects further away from this will be colored solid with
212    the color set by setMistColor().
213    
214    :type end: float
215
216
217 .. function:: setMistIntensity(intensity)
218
219    Sets the mist intensity value.
220
221    :type start: float
222
223 .. function:: disableMist()
224
225
226    Disables mist.
227    
228    .. note:: Deprecated use setUseMist().
229
230    
231 .. function:: setUseMist(enable)
232
233    Disable or enable the mist.
234
235    :type enable: boolean
236
237
238 .. function:: setEyeSeparation(eyesep)
239
240    Sets the eye separation for stereo mode. Usually Focal Length/30 provides a confortable value.
241    
242    :arg eyesep: The distance between the left and right eye.
243    :type eyesep: float
244
245
246 .. function:: getEyeSeparation()
247
248    Gets the current eye separation for stereo mode.
249    
250    :rtype: float
251
252    
253 .. function:: setFocalLength(focallength)
254
255    Sets the focal length for stereo mode. It uses the current camera focal length as initial value.
256    
257    :arg focallength: The focal length.  
258    :type focallength: float
259
260 .. function:: getFocalLength()
261
262    Gets the current focal length for stereo mode.
263    
264    :rtype: float
265
266 .. function:: getStereoEye()
267
268    Gets the current stereoscopy eye being rendered.
269    This function is mainly used in a :class:`bge.types.KX_Scene.pre_draw` callback
270    function to customize the camera projection matrices for each
271    stereoscopic eye.
272
273    :rtype: LEFT_EYE, RIGHT_EYE
274
275 .. function:: setMaterialMode(mode)
276
277    Set the material mode to use for OpenGL rendering.
278    
279    :type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
280
281    .. note:: Changes will only affect newly created scenes.
282
283
284 .. function:: getMaterialMode(mode)
285
286    Get the material mode to use for OpenGL rendering.
287    
288    :rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
289
290
291 .. function:: setGLSLMaterialSetting(setting, enable)
292
293    Enables or disables a GLSL material setting.
294    
295    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
296    :type enable: boolean
297
298
299 .. function:: getGLSLMaterialSetting(setting, enable)
300
301    Get the state of a GLSL material setting.
302    
303    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
304    :rtype: boolean
305
306 .. function:: setAnisotropicFiltering(level)
307
308    Set the anisotropic filtering level for textures.
309    
310    :arg level: The new anisotropic filtering level to use
311    :type level: integer (must be one of 1, 2, 4, 8, 16)
312    
313    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
314    
315 .. function:: getAnisotropicFiltering()
316
317    Get the anisotropic filtering level used for textures.
318    
319    :rtype: integer (one of 1, 2, 4, 8, 16)
320
321 .. function:: setMipmapping(value)
322
323    Change how to use mipmapping.
324    
325    :type value: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
326    
327    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
328
329 .. function:: getMipmapping()
330
331    Get the current mipmapping setting.
332    
333    :rtype: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
334    
335 .. function:: drawLine(fromVec,toVec,color)
336
337    Draw a line in the 3D scene.
338    
339    :arg fromVec: the origin of the line
340    :type fromVec: list [x, y, z]
341    :arg toVec: the end of the line
342    :type toVec: list [x, y, z]
343    :arg color: the color of the line
344    :type color: list [r, g, b]
345
346
347 .. function:: enableMotionBlur(factor)
348
349    Enable the motion blur effect.
350    
351    :arg factor: the ammount of motion blur to display.
352    :type factor: float [0.0 - 1.0]
353
354
355 .. function:: disableMotionBlur()
356
357    Disable the motion blur effect.
358
359 .. function:: showFramerate(enable)
360
361    Show or hide the framerate.
362
363    :type enable: boolean
364
365 .. function:: showProfile(enable)
366
367    Show or hide the profile.
368
369    :type enable: boolean
370
371 .. function:: showProperties(enable)
372
373    Show or hide the debug properties.
374
375    :type enable: boolean
376
377 .. function:: autoDebugList(enable)
378
379    Enable or disable auto adding debug properties to the debug list.
380
381    :type enable: boolean
382
383 .. function:: clearDebugList()
384
385    Clears the debug property list.
386
387 .. function:: setVsync(value)
388
389    Set the vsync value
390
391    :arg value: One of VSYNC_OFF, VSYNC_ON, VSYNC_ADAPTIVE
392    :type value: integer
393
394 .. function:: getVsync()
395
396    Get the current vsync value
397
398    :rtype: One of VSYNC_OFF, VSYNC_ON, VSYNC_ADAPTIVE