Creating a BGE staging branch.
[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 .. code-block:: python
12
13    # Example Uses an L{SCA_MouseSensor}, and two L{KX_ObjectActuator}s to implement MouseLook::
14    # To use a mouse movement sensor "Mouse" and a
15    # motion actuator to mouse look:
16    import bge
17
18    # scale sets the speed of motion
19    scale = 1.0, 0.5
20
21    co = bge.logic.getCurrentController()
22    obj = co.owner
23    mouse = co.sensors["Mouse"]
24    lmotion = co.actuators["LMove"]
25    wmotion = co.actuators["WMove"]
26
27    # Transform the mouse coordinates to see how far the mouse has moved.
28    def mousePos():
29       x = (bge.render.getWindowWidth() / 2 - mouse.position[0]) * scale[0]
30       y = (bge.render.getWindowHeight() / 2 - mouse.position[1]) * scale[1]
31       return (x, y)
32
33    pos = mousePos()
34
35    # Set the amount of motion: X is applied in world coordinates...
36    wmotion.useLocalTorque = False
37    wmotion.torque = ((0.0, 0.0, pos[0]))
38
39    # ...Y is applied in local coordinates
40    lmotion.useLocalTorque = True
41    lmotion.torque = ((-pos[1], 0.0, 0.0))
42
43    # Activate both actuators
44    co.activate(lmotion)
45    co.activate(wmotion)
46
47    # Centre the mouse
48    bge.render.setMousePosition(int(bge.render.getWindowWidth() / 2), int(bge.render.getWindowHeight() / 2))
49
50 *********
51 Constants
52 *********
53
54 .. data:: KX_TEXFACE_MATERIAL
55
56    Materials as defined by the texture face settings.
57
58 .. data:: KX_BLENDER_MULTITEX_MATERIAL
59
60    Materials approximating blender materials with multitexturing.
61
62 .. data:: KX_BLENDER_GLSL_MATERIAL
63
64    Materials approximating blender materials with GLSL.
65
66 *********
67 Functions
68 *********
69
70 .. function:: getWindowWidth()
71
72    Gets the width of the window (in pixels)
73    
74    :rtype: integer
75
76 .. function:: getWindowHeight()
77
78    Gets the height of the window (in pixels)
79    
80    :rtype: integer
81
82 .. function:: setWindowSize(width, height)
83
84    Set the width and height of the window (in pixels). This also works for fullscreen applications.
85    
86    :type width: integer
87    :type height: integer
88
89 .. function:: setFullScreen(enable)
90
91    Set whether or not the window should be fullscreen.
92    
93    :type enable: bool
94
95 .. function:: getFullScreen()
96
97    Returns whether or not the window is fullscreen.
98    
99    :rtype: bool
100
101 .. function:: makeScreenshot(filename)
102
103    Writes a screenshot to the given filename.
104    
105    If filename starts with // the image will be saved relative to the current directory.
106    If the filename contains # it will be replaced with the frame number.
107    
108    The standalone player saves .png files. It does not support color space conversion 
109    or gamma correction.
110    
111    When run from Blender, makeScreenshot supports all Blender image file formats like PNG, TGA, Jpeg and OpenEXR.
112    Gamma, Colorspace conversion and Jpeg compression are taken from the Render settings panels.
113    
114    :type filename: string
115
116
117 .. function:: enableVisibility(visible)
118
119    Doesn't really do anything...
120
121
122 .. function:: showMouse(visible)
123
124    Enables or disables the operating system mouse cursor.
125    
126    :type visible: boolean
127
128
129 .. function:: setMousePosition(x, y)
130
131    Sets the mouse cursor position.
132    
133    :type x: integer
134    :type y: integer
135
136
137 .. function:: setBackgroundColor(rgba)
138
139    Sets the window background color.
140    
141    :type rgba: list [r, g, b, a]
142
143
144 .. function:: setMistColor(rgb)
145
146    Sets the mist color.
147    
148    :type rgb: list [r, g, b]
149
150    
151 .. function:: setAmbientColor(rgb)
152
153    Sets the color of ambient light.
154    
155    :type rgb: list [r, g, b]
156
157
158 .. function:: setMistStart(start)
159
160    Sets the mist start value.  Objects further away than start will have mist applied to them.
161    
162    :type start: float
163
164
165 .. function:: setMistEnd(end)
166
167    Sets the mist end value.  Objects further away from this will be colored solid with
168    the color set by setMistColor().
169    
170    :type end: float
171
172    
173 .. function:: disableMist()
174
175    Disables mist.
176    
177    .. note:: Set any of the mist properties to enable mist.
178
179    
180 .. function:: setEyeSeparation(eyesep)
181
182    Sets the eye separation for stereo mode. Usually Focal Length/30 provides a confortable value.
183    
184    :arg eyesep: The distance between the left and right eye.
185    :type eyesep: float
186
187
188 .. function:: getEyeSeparation()
189
190    Gets the current eye separation for stereo mode.
191    
192    :rtype: float
193
194    
195 .. function:: setFocalLength(focallength)
196
197    Sets the focal length for stereo mode. It uses the current camera focal length as initial value.
198    
199    :arg focallength: The focal length.  
200    :type focallength: float
201
202 .. function:: getFocalLength()
203
204    Gets the current focal length for stereo mode.
205    
206    :rtype: float
207
208 .. function:: setMaterialMode(mode)
209
210    Set the material mode to use for OpenGL rendering.
211    
212    :type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
213
214    .. note:: Changes will only affect newly created scenes.
215
216
217 .. function:: getMaterialMode(mode)
218
219    Get the material mode to use for OpenGL rendering.
220    
221    :rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
222
223
224 .. function:: setGLSLMaterialSetting(setting, enable)
225
226    Enables or disables a GLSL material setting.
227    
228    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
229    :type enable: boolean
230
231
232 .. function:: getGLSLMaterialSetting(setting, enable)
233
234    Get the state of a GLSL material setting.
235    
236    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
237    :rtype: boolean
238
239 .. function:: setAnisotropicFiltering(level)
240
241    Set the anisotropic filtering level for textures.
242    
243    :arg level: The new anisotropic filtering level to use
244    :type level: integer (must be one of 1, 2, 4, 8, 16)
245    
246    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
247    
248 .. function:: getAnisotropicFiltering()
249
250    Get the anisotropic filtering level used for textures.
251    
252    :rtype: integer (one of 1, 2, 4, 8, 16)
253
254 .. function:: setMipmapping(value)
255
256    Change how to use mipmapping.
257    
258    :type value: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
259    
260    .. note:: Changing this value can cause all textures to be recreated, which can be slow.
261
262 .. function:: getMipmapping()
263
264    Get the current mipmapping setting.
265    
266    :rtype: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR
267    
268 .. function:: drawLine(fromVec,toVec,color)
269
270    Draw a line in the 3D scene.
271    
272    :arg fromVec: the origin of the line
273    :type fromVec: list [x, y, z]
274    :arg toVec: the end of the line
275    :type toVec: list [x, y, z]
276    :arg color: the color of the line
277    :type color: list [r, g, b]
278
279
280 .. function:: enableMotionBlur(factor)
281
282    Enable the motion blur effect.
283    
284    :arg factor: the ammount of motion blur to display.
285    :type factor: float [0.0 - 1.0]
286
287
288 .. function:: disableMotionBlur()
289
290    Disable the motion blur effect.
291