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