BGE API - small changes
[blender.git] / source / gameengine / PyDoc / Rasterizer.py
1 # $Id$
2 """
3 Documentation for the Rasterizer module.
4
5 Example Uses an L{SCA_MouseSensor}, and two L{KX_ObjectActuator}s to implement MouseLook::
6         # To use a mouse movement sensor "Mouse" and a 
7         # motion actuator to mouse look:
8         import Rasterizer
9         import GameLogic
10
11         # SCALE sets the speed of motion
12         SCALE=[1, 0.5]
13         
14         co = GameLogic.getCurrentController()
15         obj = co.getOwner()
16         mouse = co.getSensor("Mouse")
17         lmotion = co.getActuator("LMove")
18         wmotion = co.getActuator("WMove")
19         
20         # Transform the mouse coordinates to see how far the mouse has moved.
21         def mousePos():
22                 x = (Rasterizer.getWindowWidth()/2 - mouse.getXPosition())*SCALE[0]
23                 y = (Rasterizer.getWindowHeight()/2 - mouse.getYPosition())*SCALE[1]
24                 return (x, y)
25         
26         pos = mousePos()
27         
28         # Set the amount of motion: X is applied in world coordinates...
29         lmotion.setTorque(0.0, 0.0, pos[0], False)
30         # ...Y is applied in local coordinates
31         wmotion.setTorque(-pos[1], 0.0, 0.0, True)
32         
33         # Activate both actuators
34         GameLogic.addActiveActuator(lmotion, True)
35         GameLogic.addActiveActuator(wmotion, True)
36         
37         # Centre the mouse
38         Rasterizer.setMousePosition(Rasterizer.getWindowWidth()/2, Rasterizer.getWindowHeight()/2)
39
40 @group Material Types: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
41 @var KX_TEXFACE_MATERIAL: Materials as defined by the texture face settings.
42 @var KX_BLENDER_MULTITEX_MATERIAL: Materials approximating blender materials with multitexturing.
43 @var KX_BLENDER_GLSL_MATERIAL: Materials approximating blender materials with GLSL.
44
45 """
46
47 def getScreenPosition(arg):
48         """
49         Gets the position of an object projected on screen space.
50
51         Example:
52         # For an object in the middle of the screen, coord = [0.5,0.5]
53         coord = Rasterizer.getScreenPosition(object)
54
55         @param arg: L{KX_GameObject}, object name or list [x, y, z]
56         @rtype: list [x, y]
57         @return: the object's position in screen coordinates.
58         """
59 def getScreenVect(x, y):
60         """
61         Gets the vector from the camera position in the screen coordinate direction.
62
63         Example:
64         # Gets the vector of the camera front direction:
65         m_vect = Rasterizer.getScreenVect(0.5,0.5)
66
67         @type x: float
68         @type y: float
69         @rtype: 3d vector
70         @return: the vector from a screen coordinate.
71         """
72 def getScreenRay(x, y, dist, property):
73         """
74         Look towards a screen coordinate (x,y) and find first object hit within dist that matches prop.
75         The ray is similar to KX_GameObject->rayCastTo.
76
77         Example:
78         # Gets an object with a property "wall" in front of the camera within a distance of 100:
79         target = Rasterizer.getScreenRay(0.5,0.5,100,"wall")
80
81         @type x: float
82         @type y: float
83         @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
84         @type dist: float
85         @param property: property name that object must have; can be omitted => detect any object
86         @type property: string
87         @rtype: L{KX_GameObject}
88         @return: the first object hit or None if no object or object does not match prop
89         """
90 def getWindowWidth():
91         """
92         Gets the width of the window (in pixels)
93         
94         @rtype: integer
95         """
96 def getWindowHeight():
97         """
98         Gets the height of the window (in pixels)
99         
100         @rtype: integer
101         """
102 def makeScreenshot(filename):
103         """
104         Writes a screenshot to the given filename.
105         
106         If filename starts with // the image will be saved relative to the current directory.
107         If the filename contains # it will be replaced with the frame number.
108         
109         The standalone player saves .png files. It does not support colour space conversion 
110         or gamma correction.
111         
112         When run from Blender, makeScreenshot supports Iris, IrisZ, TGA, Raw TGA, PNG, HamX, and Jpeg.
113         Gamma, Colourspace conversion and Jpeg compression are taken from the Render settings panels.
114         
115         @type filename: string
116         """
117
118 def enableVisibility(visible):
119         """
120         Doesn't really do anything...
121         """
122
123 def showMouse(visible):
124         """
125         Enables or disables the operating system mouse cursor.
126         
127         @type visible: boolean
128         """
129
130 def setMousePosition(x, y):
131         """
132         Sets the mouse cursor position.
133         
134         @type x: integer
135         @type y: integer
136         """
137
138 def setBackgroundColor(rgba):
139         """
140         Sets the window background colour.
141         
142         @type rgba: list [r, g, b, a]
143         """
144
145 def setMistColor(rgb):
146         """
147         Sets the mist colour.
148         
149         @type rgb: list [r, g, b]
150         """
151         
152 def setAmbientColor(rgb):
153         """
154         Sets the color of ambient light.
155         
156         @type rgb: list [r, g, b]
157         """
158
159 def setMistStart(start):
160         """
161         Sets the mist start value.  Objects further away than start will have mist applied to them.
162         
163         @type start: float
164         """
165
166 def setMistEnd(end):
167         """
168         Sets the mist end value.  Objects further away from this will be coloured solid with
169         the colour set by setMistColor().
170         
171         @type end: float
172         """
173         
174 def disableMist():
175         """
176         Disables mist.
177         
178         @note: Set any of the mist properties to enable mist.
179         """
180         
181 def setEyeSeparation(eyesep):
182         """
183         Sets the eye separation for stereo mode.
184         
185         @param eyesep: The distance between the left and right eye.
186         @type eyesep: float
187         """
188
189 def getEyeSeparation():
190         """
191         Gets the current eye separation for stereo mode.
192         
193         @rtype: float
194         """
195         
196 def setFocalLength(focallength):
197         """
198         Sets the focal length for stereo mode.
199         
200         @param focallength: The focal length.  
201         @type focallength: float
202         """
203
204 def getFocalLength():
205         """
206         Gets the current focal length for stereo mode.
207         
208         @rtype: float
209         """
210
211 def setMaterialMode(mode):
212         """
213         Set the material mode to use for OpenGL rendering.
214         
215         @type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
216         @note: Changes will only affect newly created scenes.
217         """
218
219 def getMaterialMode(mode):
220         """
221         Get the material mode to use for OpenGL rendering.
222         
223         @rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL
224         """
225
226 def setGLSLMaterialSetting(setting, enable):
227         """
228         Enables or disables a GLSL material setting.
229         
230         @type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
231         @type enable: boolean
232         """
233
234 def getGLSLMaterialSetting(setting, enable):
235         """
236         Get the state of a GLSL material setting.
237         
238         @type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures)
239         @rtype: boolean
240         """
241
242 def drawLine(fromVec,toVec,color):
243         """
244         Draw a line in the 3D scene.
245         
246         @param fromVec: the origin of the line
247         @type fromVec: list [x, y, z]
248         @param toVec: the end of the line
249         @type toVec: list [x, y, z]
250         @param color: the color of the line
251         @type color: list [r, g, b]
252         """
253
254 def enableMotionBlur(factor):
255         """
256         Enable the motion blue effect.
257         
258         @param factor: the ammount of motion blur to display.
259         @type factor: float [0.0 - 1.0]
260         """
261
262 def disableMotionBlur():
263         """
264         Disable the motion blue effect.
265         """