baf60ec0c970580d0c9543f47bd5e5340266fcb6
[blender.git] / doc / python_api / rst / bge_types / bge.types.KX_Camera.rst
1 KX_Camera(KX_GameObject)
2 ========================
3
4 .. module:: bge.types
5
6 base class --- :class:`KX_GameObject`
7
8 .. class:: KX_Camera(KX_GameObject)
9
10    A Camera object.
11
12    .. data:: INSIDE
13
14       See :data:`sphereInsideFrustum` and :data:`boxInsideFrustum`
15
16    .. data:: INTERSECT
17
18       See :data:`sphereInsideFrustum` and :data:`boxInsideFrustum`
19
20    .. data:: OUTSIDE
21
22       See :data:`sphereInsideFrustum` and :data:`boxInsideFrustum`
23
24    .. attribute:: lens
25
26       The camera's lens value.
27
28       :type: float
29
30    .. attribute:: ortho_scale
31
32       The camera's view scale when in orthographic mode.
33
34       :type: float
35
36    .. attribute:: near
37
38       The camera's near clip distance.
39
40       :type: float
41
42    .. attribute:: far
43
44       The camera's far clip distance.
45
46       :type: float
47
48    .. attribute:: perspective
49
50       True if this camera has a perspective transform, False for an orthographic projection.
51
52       :type: boolean
53
54    .. attribute:: frustum_culling
55
56       True if this camera is frustum culling.
57
58       :type: boolean
59
60    .. attribute:: projection_matrix
61
62       This camera's 4x4 projection matrix.
63
64       .. note::
65       
66          This is the identity matrix prior to rendering the first frame (any Python done on frame 1). 
67
68       :type: 4x4 Matrix [[float]]
69
70    .. attribute:: modelview_matrix
71
72       This camera's 4x4 model view matrix. (read-only).
73
74       :type: 4x4 Matrix [[float]]
75
76       .. note::
77       
78          This matrix is regenerated every frame from the camera's position and orientation. Also, this is the identity matrix prior to rendering the first frame (any Python done on frame 1).
79
80    .. attribute:: camera_to_world
81
82       This camera's camera to world transform. (read-only).
83
84       :type: 4x4 Matrix [[float]]
85
86       .. note::
87       
88          This matrix is regenerated every frame from the camera's position and orientation.
89
90    .. attribute:: world_to_camera
91
92       This camera's world to camera transform. (read-only).
93
94       :type: 4x4 Matrix [[float]]
95
96       .. note::
97          
98          Regenerated every frame from the camera's position and orientation.
99
100       .. note::
101       
102          This is camera_to_world inverted.
103
104    .. attribute:: useViewport
105
106       True when the camera is used as a viewport, set True to enable a viewport for this camera.
107
108       :type: boolean
109
110    .. method:: sphereInsideFrustum(centre, radius)
111
112       Tests the given sphere against the view frustum.
113
114       :arg centre: The centre of the sphere (in world coordinates.)
115       :type centre: list [x, y, z]
116       :arg radius: the radius of the sphere
117       :type radius: float
118       :return: :data:`~bge.types.KX_Camera.INSIDE`, :data:`~bge.types.KX_Camera.OUTSIDE` or :data:`~bge.types.KX_Camera.INTERSECT`
119       :rtype: integer
120
121       .. note::
122
123          When the camera is first initialized the result will be invalid because the projection matrix has not been set.
124
125       .. code-block:: python
126
127          from bge import logic
128          cont = logic.getCurrentController()
129          cam = cont.owner
130          
131          # A sphere of radius 4.0 located at [x, y, z] = [1.0, 1.0, 1.0]
132          if (cam.sphereInsideFrustum([1.0, 1.0, 1.0], 4) != cam.OUTSIDE):
133              # Sphere is inside frustum !
134              # Do something useful !
135          else:
136              # Sphere is outside frustum
137
138    .. method:: boxInsideFrustum(box)
139
140       Tests the given box against the view frustum.
141
142       :arg box: Eight (8) corner points of the box (in world coordinates.)
143       :type box: list of lists
144       :return: :data:`~bge.types.KX_Camera.INSIDE`, :data:`~bge.types.KX_Camera.OUTSIDE` or :data:`~bge.types.KX_Camera.INTERSECT`
145
146       .. note::
147       
148          When the camera is first initialized the result will be invalid because the projection matrix has not been set.
149
150       .. code-block:: python
151
152          from bge import logic
153          cont = logic.getCurrentController()
154          cam = cont.owner
155
156          # Box to test...
157          box = []
158          box.append([-1.0, -1.0, -1.0])
159          box.append([-1.0, -1.0,  1.0])
160          box.append([-1.0,  1.0, -1.0])
161          box.append([-1.0,  1.0,  1.0])
162          box.append([ 1.0, -1.0, -1.0])
163          box.append([ 1.0, -1.0,  1.0])
164          box.append([ 1.0,  1.0, -1.0])
165          box.append([ 1.0,  1.0,  1.0])
166          
167          if (cam.boxInsideFrustum(box) != cam.OUTSIDE):
168            # Box is inside/intersects frustum !
169            # Do something useful !
170          else:
171            # Box is outside the frustum !
172            
173    .. method:: pointInsideFrustum(point)
174
175       Tests the given point against the view frustum.
176
177       :arg point: The point to test (in world coordinates.)
178       :type point: 3D Vector
179       :return: True if the given point is inside this camera's viewing frustum.
180       :rtype: boolean
181
182       .. note::
183       
184          When the camera is first initialized the result will be invalid because the projection matrix has not been set.
185
186       .. code-block:: python
187
188          from bge import logic
189          cont = logic.getCurrentController()
190          cam = cont.owner
191
192          # Test point [0.0, 0.0, 0.0]
193          if (cam.pointInsideFrustum([0.0, 0.0, 0.0])):
194            # Point is inside frustum !
195            # Do something useful !
196          else:
197            # Box is outside the frustum !
198
199    .. method:: getCameraToWorld()
200
201       Returns the camera-to-world transform.
202
203       :return: the camera-to-world transform matrix.
204       :rtype: matrix (4x4 list)
205
206    .. method:: getWorldToCamera()
207
208       Returns the world-to-camera transform.
209
210       This returns the inverse matrix of getCameraToWorld().
211
212       :return: the world-to-camera transform matrix.
213       :rtype: matrix (4x4 list)
214
215    .. method:: setOnTop()
216
217       Set this cameras viewport ontop of all other viewport.
218
219    .. method:: setViewport(left, bottom, right, top)
220
221       Sets the region of this viewport on the screen in pixels.
222
223       Use :data:`bge.render.getWindowHeight` and :data:`bge.render.getWindowWidth` to calculate values relative to the entire display.
224
225       :arg left: left pixel coordinate of this viewport
226       :type left: integer
227       :arg bottom: bottom pixel coordinate of this viewport
228       :type bottom: integer
229       :arg right: right pixel coordinate of this viewport
230       :type right: integer
231       :arg top: top pixel coordinate of this viewport
232       :type top: integer
233
234    .. method:: getScreenPosition(object)
235
236       Gets the position of an object projected on screen space.
237
238       .. code-block:: python
239
240          # For an object in the middle of the screen, coord = [0.5, 0.5]
241          coord = camera.getScreenPosition(object)
242
243       :arg object: object name or list [x, y, z]
244       :type object: :class:`KX_GameObject` or 3D Vector
245       :return: the object's position in screen coordinates.
246       :rtype: list [x, y]
247
248    .. method:: getScreenVect(x, y)
249
250       Gets the vector from the camera position in the screen coordinate direction.
251
252       :arg x: X Axis
253       :type x: float
254       :arg y: Y Axis
255       :type y: float
256       :rtype: 3D Vector
257       :return: The vector from screen coordinate.
258
259       .. code-block:: python
260
261          # Gets the vector of the camera front direction:
262          m_vect = camera.getScreenVect(0.5, 0.5)
263
264    .. method:: getScreenRay(x, y, dist=inf, property=None)
265
266       Look towards a screen coordinate (x, y) and find first object hit within dist that matches prop.
267       The ray is similar to KX_GameObject->rayCastTo.
268
269       :arg x: X Axis
270       :type x: float
271       :arg y: Y Axis
272       :type y: float
273       :arg dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
274       :type dist: float
275       :arg property: property name that object must have; can be omitted => detect any object
276       :type property: string
277       :rtype: :class:`KX_GameObject`
278       :return: the first object hit or None if no object or object does not match prop
279
280       .. code-block:: python
281
282          # Gets an object with a property "wall" in front of the camera within a distance of 100:
283          target = camera.getScreenRay(0.5, 0.5, 100, "wall")
284