== python api docs ==
[blender.git] / source / gameengine / PyDoc / bge.render.rst
1
2 Game Engine bge.render Module
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.render
17    import bge.logic
18
19    # SCALE sets the speed of motion
20    SCALE=[1, 0.5]
21    
22    co = bge.logic.getCurrentController()
23    obj = co.getOwner()
24    mouse = co.getSensor("Mouse")
25    lmotion = co.getActuator("LMove")
26    wmotion = co.getActuator("WMove")
27    
28    # Transform the mouse coordinates to see how far the mouse has moved.
29    def mousePos():
30       x = (bge.render.getWindowWidth()/2 - mouse.getXPosition())*SCALE[0]
31       y = (bge.render.getWindowHeight()/2 - mouse.getYPosition())*SCALE[1]
32       return (x, y)
33    
34    pos = mousePos()
35    
36    # Set the amount of motion: X is applied in world coordinates...
37    lmotion.setTorque(0.0, 0.0, pos[0], False)
38    # ...Y is applied in local coordinates
39    wmotion.setTorque(-pos[1], 0.0, 0.0, True)
40    
41    # Activate both actuators
42    bge.logic.addActiveActuator(lmotion, True)
43    bge.logic.addActiveActuator(wmotion, True)
44    
45    # Centre the mouse
46    bge.render.setMousePosition(bge.render.getWindowWidth()/2, bge.render.getWindowHeight()/2)
47
48 *********
49 Constants
50 *********
51
52 .. data:: KX_TEXFACE_MATERIAL
53
54    Materials as defined by the texture face settings.
55
56 .. data:: KX_BLENDER_MULTITEX_MATERIAL
57
58    Materials approximating blender materials with multitexturing.
59
60 .. data:: KX_BLENDER_GLSL_MATERIAL
61
62    Materials approximating blender materials with GLSL.
63
64 *********
65 Functions
66 *********
67
68 .. function:: getWindowWidth()
69
70    Gets the width of the window (in pixels)
71    
72    :rtype: integer
73
74 .. function:: getWindowHeight()
75
76    Gets the height of the window (in pixels)
77    
78    :rtype: integer
79
80 .. function:: makeScreenshot(filename)
81
82    Writes a screenshot to the given filename.
83    
84    If filename starts with // the image will be saved relative to the current directory.
85    If the filename contains # it will be replaced with the frame number.
86    
87    The standalone player saves .png files. It does not support colour space conversion 
88    or gamma correction.
89    
90    When run from Blender, makeScreenshot supports Iris, IrisZ, TGA, Raw TGA, PNG, HamX, and Jpeg.
91    Gamma, Colourspace conversion and Jpeg compression are taken from the Render settings panels.
92    
93    :type filename: string
94
95
96 .. function:: enableVisibility(visible)
97
98    Doesn't really do anything...
99
100
101 .. function:: showMouse(visible)
102
103    Enables or disables the operating system mouse cursor.
104    
105    :type visible: boolean
106
107
108 .. function:: setMousePosition(x, y)
109
110    Sets the mouse cursor position.
111    
112    :type x: integer
113    :type y: integer
114
115
116 .. function:: setBackgroundColor(rgba)
117
118    Sets the window background colour.
119    
120    :type rgba: list [r, g, b, a]
121
122
123 .. function:: setMistColor(rgb)
124
125    Sets the mist colour.
126    
127    :type rgb: list [r, g, b]
128
129    
130 .. function:: setAmbientColor(rgb)
131
132    Sets the color of ambient light.
133    
134    :type rgb: list [r, g, b]
135
136
137 .. function:: setMistStart(start)
138
139    Sets the mist start value.  Objects further away than start will have mist applied to them.
140    
141    :type start: float
142
143
144 .. function:: setMistEnd(end)
145
146    Sets the mist end value.  Objects further away from this will be coloured solid with
147    the colour set by setMistColor().
148    
149    :type end: float
150
151    
152 .. function:: disableMist()
153
154    Disables mist.
155    
156    .. note:: Set any of the mist properties to enable mist.
157
158    
159 .. function:: setEyeSeparation(eyesep)
160
161    Sets the eye separation for stereo mode. Usually Focal Length/30 provides a confortable value.
162    
163    :arg eyesep: The distance between the left and right eye.
164    :type eyesep: float
165
166
167 .. function:: getEyeSeparation()
168
169    Gets the current eye separation for stereo mode.
170    
171    :rtype: float
172
173    
174 .. function:: setFocalLength(focallength)
175
176    Sets the focal length for stereo mode. It uses the current camera focal length as initial value.
177    
178    :arg focallength: The focal length.  
179    :type focallength: float
180
181 .. function:: getFocalLength()
182
183    Gets the current focal length for stereo mode.
184    
185    :rtype: float
186
187 .. function:: setMaterialMode(mode)
188
189    Set the material mode to use for OpenGL rendering.
190    
191    :type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
192
193    .. note:: Changes will only affect newly created scenes.
194
195
196 .. function:: getMaterialMode(mode)
197
198    Get the material mode to use for OpenGL rendering.
199    
200    :rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
201
202
203 .. function:: setGLSLMaterialSetting(setting, enable)
204
205    Enables or disables a GLSL material setting.
206    
207    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
208    :type enable: boolean
209
210
211 .. function:: getGLSLMaterialSetting(setting, enable)
212
213    Get the state of a GLSL material setting.
214    
215    :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
216    :rtype: boolean
217
218
219 .. function:: drawLine(fromVec,toVec,color)
220
221    Draw a line in the 3D scene.
222    
223    :arg fromVec: the origin of the line
224    :type fromVec: list [x, y, z]
225    :arg toVec: the end of the line
226    :type toVec: list [x, y, z]
227    :arg color: the color of the line
228    :type color: list [r, g, b]
229
230
231 .. function:: enableMotionBlur(factor)
232
233    Enable the motion blue effect.
234    
235    :arg factor: the ammount of motion blur to display.
236    :type factor: float [0.0 - 1.0]
237
238
239 .. function:: disableMotionBlur()
240
241    Disable the motion blue effect.
242