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