some corrections to bge.texture docs
[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