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