← Back to branch summary

~ubuntu-branches/ubuntu/saucy/blender/saucy-proposed

« back to all changes in this revision

Viewing changes to doc/python_api/rst/bge_types/bge.types.KX_Camera.rst

  • Committer: Package Import Robot
  • Author(s): Jeremy Bicha
  • Date: 2013-03-06 12:08:47 UTC
  • mfrom: (1.5.1) (14.1.8 experimental)
  • Revision ID: package-import@ubuntu.com-20130306120847-frjfaryb2zrotwcg
Tags: 2.66a-1ubuntu1
https://launchpad.net/bugs/1076930
https://launchpad.net/bugs/1089256
https://launchpad.net/bugs/1052743
https://launchpad.net/bugs/999024
* Resynchronize with Debian (LP: #1076930, #1089256, #1052743, #999024,
  #1122888, #1147084)
* debian/control:
  - Lower build-depends on libavcodec-dev since we're not
    doing the libav9 transition in Ubuntu yet

Show diffs side-by-side

added added

removed removed

Lines of Context:
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