49016d1e03d8f66f2ea6becfc1449d3057ff4b60
[blender-staging.git] / doc / python_api / rst / bge.texture.rst
1
2 Game Engine bge.texture Module
3 ==============================
4
5 .. note::
6         This documentation is still very weak, and needs some help! Right now they are mostly a collection
7         of the docstrings found in the bge.texture source code + some random places filled with text.
8
9 *****
10 Intro
11 *****
12
13 The bge.texture module allows you to manipulate textures during the game.
14
15 Several sources for texture are possible: video files, image files, video capture, memory buffer, camera render or a mix of that.
16
17 The video and image files can be loaded from the internet using an URL instead of a file name.
18
19 In addition, you can apply filters on the images before sending them to the GPU, allowing video effect: blue screen, color band, gray, normal map.
20
21 bge.texture uses FFmpeg to load images and videos. All the formats and codecs that FFmpeg supports are supported by this module, including but not limited to::
22
23         * AVI
24         * Ogg
25         * Xvid
26         * Theora
27         * dv1394 camera
28         * video4linux capture card (this includes many webcams)
29         * videoForWindows capture card (this includes many webcams)
30         * JPG 
31
32 The principle is simple: first you identify a texture on an existing object using 
33 the :materialID: function, then you create a new texture with dynamic content
34 and swap the two textures in the GPU.
35
36 The GE is not aware of the substitution and continues to display the object as always, 
37 except that you are now in control of the texture.
38
39 When the texture object is deleted, the new texture is deleted and the old texture restored.
40
41 .. module:: bge.texture
42
43 .. class:: VideoFFmpeg(file [, capture=-1, rate=25.0, width=0, height=0])
44
45         FFmpeg video source
46    
47         .. attribute:: status
48                 video status
49                 
50         .. attribute::  range
51                 replay range
52                 
53         .. attribute:: repeat
54                 repeat count, -1 for infinite repeat
55                 
56                 :type: int
57         
58         .. attribute:: framerate
59                 frame rate
60                 
61                 :type: float
62                 
63         .. attribute:: valid
64                 Tells if an image is available
65                 
66                 :type: bool
67                 
68         .. attribute:: image
69                 image data
70                 
71         .. attribute:: size
72                 image size
73                 
74         .. attribute:: scale
75                 fast scale of image (near neighbour)
76                 
77         .. attribute:: flip
78                 flip image vertically
79                 
80         .. attribute:: filter
81                 pixel filter
82                 
83         .. attribute:: preseek
84                 number of frames of preseek
85                 
86                 :type: int
87                 
88         .. attribute:: deinterlace
89                 deinterlace image
90                 
91                 :type: bool
92    
93         .. method:: play()
94                 Play (restart) video
95                 
96         .. method:: pause()
97                 pause video
98                 
99         .. method:: stop()
100                 stop video (play will replay it from start)
101                 
102         .. method:: refresh()
103                 Refresh video - get its status
104
105 .. class:: ImageFFmpeg(file)
106
107         FFmpeg image source
108         
109         .. attribute:: status
110                 video status
111         
112         .. attribute:: valid
113                 Tells if an image is available
114                 
115                 :type: bool
116                 
117         .. attribute:: image
118                 image data
119                 
120         .. attribute:: size
121                 image size
122                 
123         .. attribute:: scale
124                 fast scale of image (near neighbour)
125                 
126         .. attribute:: flip
127                 flip image vertically
128                 
129         .. attribute:: filter
130                 pixel filter
131                 
132         .. method:: refresh()
133                 Refresh image, i.e. load it
134                 
135         .. method:: reload([newname])
136                 Reload image, i.e. reopen it
137                 
138 .. class:: ImageBuff()
139         
140         Image source from image buffer
141         
142         .. attribute:: filter
143                 pixel filter
144         
145         .. attribute:: flip
146                 flip image vertically
147         
148         .. attribute:: image
149                 image data
150         
151         .. method:: load(imageBuffer, width, height)
152                 Load image from buffer
153         
154         .. method:: plot(imageBuffer, width, height, positionX, positionY)
155                 update image buffer
156         
157         .. attribute:: scale
158                 fast scale of image (near neighbour)
159         
160         .. attribute:: size
161                 image size
162         
163         .. attribute:: valid
164                 bool to tell if an image is available
165
166 .. class:: ImageMirror(scene)
167         
168         Image source from mirror
169         
170         .. attribute:: alpha
171                 use alpha in texture
172         
173         .. attribute:: background
174                 background color
175         
176         .. attribute:: capsize
177                 size of render area
178         
179         .. attribute:: clip
180                 clipping distance
181         
182         .. attribute:: filter
183                 pixel filter
184         
185         .. attribute:: flip
186                 flip image vertically
187         
188         .. attribute:: image
189                 image data
190         
191         .. method:: refresh(imageMirror)
192                 Refresh image - invalidate its current content
193         
194         .. attribute:: scale
195                 fast scale of image (near neighbour)
196         
197         .. attribute:: size
198                 image size
199         
200         .. attribute:: valid
201                 bool to tell if an image is available
202         
203         .. attribute:: whole
204                 use whole viewport to render
205
206 .. class:: ImageMix()
207         
208         Image mixer
209         
210         .. attribute:: filter
211                 pixel filter
212         
213         .. attribute:: flip
214                 flip image vertically
215         
216         .. method:: getSource(imageMix)
217                 get image source
218         
219         .. method:: getWeight(imageMix)
220                 get image source weight
221         
222         .. attribute:: image
223                 image data
224         
225         .. method:: refresh(imageMix)
226                 Refresh image - invalidate its current content
227         
228         .. attribute:: scale
229                 fast scale of image (near neighbour)
230         
231         .. method:: setSource(imageMix)
232                 set image source
233         
234         .. method:: setWeight(imageMix)
235                 set image source weight
236         
237         .. attribute:: valid
238                 bool to tell if an image is available
239
240 .. class:: ImageRender(scene, camera)
241         
242         Image source from render
243         
244         .. attribute:: alpha
245                 use alpha in texture
246         
247         .. attribute:: background
248                 background color
249         
250         .. attribute:: capsize
251                 size of render area
252         
253         .. attribute:: filter
254                 pixel filter
255         
256         .. attribute:: flip
257                 flip image vertically
258         
259         .. attribute:: image
260                 image data
261         
262         .. method:: refresh(imageRender)
263                 Refresh image - invalidate its current content
264         
265         .. attribute:: scale
266                 fast scale of image (near neighbour)
267         
268         .. attribute:: size
269                 image size
270         
271         .. attribute:: valid
272                 bool to tell if an image is available
273         
274         .. attribute:: whole
275                 use whole viewport to render
276
277 .. class:: ImageViewport()
278         
279         Image source from viewport
280         
281         .. attribute:: alpha
282                 use alpha in texture
283         
284         .. attribute:: capsize
285                 size of viewport area being captured
286         
287         .. attribute:: filter
288                 pixel filter
289         
290         .. attribute:: flip
291                 flip image vertically
292         
293         .. attribute:: image
294                 image data
295         
296         .. attribute:: position
297                 upper left corner of captured area
298         
299         .. method:: refresh(imageViewport)
300                 Refresh image - invalidate its current content
301         
302         .. attribute:: scale
303                 fast scale of image (near neighbour)
304         
305         .. attribute:: size
306                 image size
307         
308         .. attribute:: valid
309                 bool to tell if an image is available
310         
311         .. attribute:: whole
312                 use whole viewport to capture
313
314 .. class:: Texture(gameObj)
315         
316         Texture objects
317         
318         .. attribute:: bindId
319                 OpenGL Bind Name
320         
321         .. method:: close(texture)
322                 Close dynamic texture and restore original
323         
324         .. attribute:: mipmap
325                 mipmap texture
326         
327         .. method:: refresh(texture)
328                 Refresh texture from source
329         
330         .. attribute:: source
331                 source of texture
332
333 .. class:: FilterBGR24()
334         
335         Source filter BGR24 objects
336
337 .. class:: FilterBlueScreen()
338         
339         Filter for Blue Screen objects
340         
341         .. attribute:: color
342                 blue screen color
343         
344         .. attribute:: limits
345                 blue screen color limits
346         
347         .. attribute:: previous
348                 previous pixel filter
349
350 .. class:: FilterColor()
351         
352         Filter for color calculations
353         
354         .. attribute:: matrix
355                 matrix [4][5] for color calculation
356         
357         .. attribute:: previous
358                 previous pixel filter
359
360 .. class:: FilterGray()
361         
362         Filter for gray scale effect
363         
364         .. attribute:: previous
365                 previous pixel filter
366
367 .. class:: FilterLevel()
368         
369         Filter for levels calculations
370         
371         .. attribute:: levels
372                 levels matrix [4] (min, max)
373         
374         .. attribute:: previous
375                 previous pixel filter
376
377 .. class:: FilterNormal()
378         
379         Filter for Blue Screen objects
380         
381         .. attribute:: colorIdx
382                 index of color used to calculate normal (0 - red, 1 - green, 2 - blue)
383         
384         .. attribute:: depth
385                 depth of relief
386         
387         .. attribute:: previous
388                 previous pixel filter
389
390 .. class:: FilterRGB24()
391         
392         Returns a new input filter object to be used with :class:'ImageBuff' object when the image passed
393         to the ImageBuff.load() function has the 3-bytes pixel format BGR.
394
395 .. class:: FilterRGBA32()
396         
397         Source filter RGBA32 objects
398
399 .. function:: getLastError()
400         Last error that occurred in a bge.texture function.
401         
402         :return: the description of the last error occurred in a bge.texture function.
403         :rtype: string
404         
405 .. function:: imageToArray(image,mode)
406         Returns a :class:`~bgl.buffer` corresponding to the current image stored in a texture source object.
407
408         :arg image: Image source object.
409         :type image: object of type :class:'VideoFFmpeg', :class:'ImageFFmpeg', :class:'ImageBuff', :class:'ImageMix', :class:'ImageRender', :class:'ImageMirror' or :class:'ImageViewport'
410         :arg mode: optional argument representing the pixel format. 
411 |                    You can use the characters R, G, B for the 3 color channels, A for the alpha channel, 
412 |                    0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
413 |                    Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order. 
414 |                             "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
415 |                    The default mode is "RGBA".
416
417         :type mode: string
418         :rtype: :class:`~bgl.buffer`
419         :return: A object representing the image as one dimensional array of bytes of size (pixel_size*width*height),
420         line by line starting from the bottom of the image. The pixel size and format is determined by the mode 
421         parameter.
422         
423 .. function materialID(object,name)
424         Returns a numeric value that can be used in :class:'Texture' to create a dynamic texture.
425
426         The value corresponds to an internal material number that uses the texture identified
427         by name. name is a string representing a texture name with IM prefix if you want to
428         identify the texture directly.  This method works for basic tex face and for material,
429         provided the material has a texture channel using that particular texture in first
430         position of the texture stack.  name can also have MA prefix if you want to identify
431         the texture by material. In that case the material must have a texture channel in first
432         position.
433         
434         If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
435         
436         Ex: bge.texture.materialID(obj, 'IMvideo.png')
437         
438         :arg object: the game object that uses the texture you want to make dynamic
439         :type object: game object
440         :arg name: name of the texture/material you want to make dynamic. 
441         :type name: string
442         :rtype: integer
443
444 .. function setLogFile(filename)
445         Sets the name of a text file in which runtime error messages will be written, in addition to the printing
446         of the messages on the Python console. Only the runtime errors specific to the VideoTexture module
447         are written in that file, ordinary runtime time errors are not written. 
448
449         :arg filename: name of error log file
450         :type filename: string
451         :rtype: integer