fix for example
[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
49       video status
50
51    .. attribute:: range
52
53       replay range
54
55    .. attribute:: repeat
56
57       repeat count, -1 for infinite repeat
58
59       :type: int
60
61    .. attribute:: framerate
62
63       frame rate
64
65       :type: float
66
67    .. attribute:: valid
68
69       Tells if an image is available
70
71       :type: bool
72
73    .. attribute:: image
74
75       image data
76
77    .. attribute:: size
78
79       image size
80
81    .. attribute:: scale
82
83       fast scale of image (near neighbour)
84
85    .. attribute:: flip
86
87       flip image vertically
88
89    .. attribute:: filter
90
91       pixel filter
92
93    .. attribute:: preseek
94
95       number of frames of preseek
96
97       :type: int
98
99    .. attribute:: deinterlace
100
101       deinterlace image
102
103       :type: bool
104
105    .. method:: play()
106
107       Play (restart) video
108
109    .. method:: pause()
110
111       pause video
112
113    .. method:: stop()
114
115       stop video (play will replay it from start)
116
117    .. method:: refresh()
118
119       Refresh video - get its status
120
121 .. class:: ImageFFmpeg(file)
122
123    FFmpeg image source
124
125    .. attribute:: status
126
127       video status
128
129    .. attribute:: valid
130
131       Tells if an image is available
132
133       :type: bool
134
135    .. attribute:: image
136
137       image data
138
139    .. attribute:: size
140
141       image size
142
143    .. attribute:: scale
144
145       fast scale of image (near neighbour)
146
147    .. attribute:: flip
148
149       flip image vertically
150
151    .. attribute:: filter
152
153       pixel filter
154
155    .. method:: refresh()
156
157       Refresh image, i.e. load it
158
159    .. method:: reload([newname])
160
161       Reload image, i.e. reopen it
162
163 .. class:: ImageBuff()
164
165    Image source from image buffer
166
167    .. attribute:: filter
168
169       pixel filter
170
171    .. attribute:: flip
172
173       flip image vertically
174
175    .. attribute:: image
176
177       image data
178
179    .. method:: load(imageBuffer, width, height)
180
181       Load image from buffer
182
183    .. method:: plot(imageBuffer, width, height, positionX, positionY)
184
185       update image buffer
186
187    .. attribute:: scale
188
189       fast scale of image (near neighbour)
190
191    .. attribute:: size
192
193       image size
194
195    .. attribute:: valid
196
197       bool to tell if an image is available
198
199 .. class:: ImageMirror(scene)
200
201    Image source from mirror
202
203    .. attribute:: alpha
204
205       use alpha in texture
206
207    .. attribute:: background
208
209       background color
210
211    .. attribute:: capsize
212
213       size of render area
214
215    .. attribute:: clip
216
217       clipping distance
218
219    .. attribute:: filter
220
221       pixel filter
222
223    .. attribute:: flip
224
225       flip image vertically
226
227    .. attribute:: image
228
229       image data
230
231    .. method:: refresh(imageMirror)
232
233       Refresh image - invalidate its current content
234
235    .. attribute:: scale
236
237       fast scale of image (near neighbour)
238
239    .. attribute:: size
240
241       image size
242
243    .. attribute:: valid
244
245       bool to tell if an image is available
246
247    .. attribute:: whole
248
249       use whole viewport to render
250
251 .. class:: ImageMix()
252
253    Image mixer
254
255    .. attribute:: filter
256
257       pixel filter
258
259    .. attribute:: flip
260
261       flip image vertically
262
263    .. method:: getSource(imageMix)
264
265       get image source
266
267    .. method:: getWeight(imageMix)
268
269       get image source weight
270
271
272    .. attribute:: image
273
274       image data
275
276    .. method:: refresh(imageMix)
277
278       Refresh image - invalidate its current content
279
280    .. attribute:: scale
281
282       fast scale of image (near neighbour)
283
284    .. method:: setSource(imageMix)
285
286       set image source
287
288    .. method:: setWeight(imageMix)
289
290       set image source weight
291
292    .. attribute:: valid
293
294       bool to tell if an image is available
295
296 .. class:: ImageRender(scene, camera)
297
298    Image source from render
299
300    .. attribute:: alpha
301
302       use alpha in texture
303
304    .. attribute:: background
305
306       background color
307
308    .. attribute:: capsize
309
310       size of render area
311
312    .. attribute:: filter
313
314       pixel filter
315
316    .. attribute:: flip
317
318       flip image vertically
319
320    .. attribute:: image
321
322       image data
323
324    .. method:: refresh(imageRender)
325
326       Refresh image - invalidate its current content
327
328    .. attribute:: scale
329
330       fast scale of image (near neighbour)
331
332    .. attribute:: size
333
334       image size
335
336    .. attribute:: valid
337
338       bool to tell if an image is available
339
340    .. attribute:: whole
341
342       use whole viewport to render
343
344 .. class:: ImageViewport()
345
346    Image source from viewport
347
348    .. attribute:: alpha
349
350       use alpha in texture
351
352    .. attribute:: capsize
353
354       size of viewport area being captured
355
356    .. attribute:: filter
357
358       pixel filter
359
360    .. attribute:: flip
361
362       flip image vertically
363
364    .. attribute:: image
365
366       image data
367
368    .. attribute:: position
369
370       upper left corner of captured area
371
372    .. method:: refresh(imageViewport)
373
374       Refresh image - invalidate its current content
375
376    .. attribute:: scale
377
378       fast scale of image (near neighbour)
379
380    .. attribute:: size
381
382       image size
383
384    .. attribute:: valid
385
386       bool to tell if an image is available
387
388    .. attribute:: whole
389
390       use whole viewport to capture
391
392 .. class:: Texture(gameObj)
393
394    Texture objects
395
396    .. attribute:: bindId
397
398       OpenGL Bind Name
399
400    .. method:: close(texture)
401
402       Close dynamic texture and restore original
403
404    .. attribute:: mipmap
405
406       mipmap texture
407
408    .. method:: refresh(texture)
409
410       Refresh texture from source
411
412    .. attribute:: source
413
414       source of texture
415
416 .. class:: FilterBGR24()
417
418    Source filter BGR24 objects
419
420 .. class:: FilterBlueScreen()
421
422    Filter for Blue Screen objects
423
424    .. attribute:: color
425
426       blue screen color
427
428    .. attribute:: limits
429
430       blue screen color limits
431
432    .. attribute:: previous
433
434       previous pixel filter
435
436 .. class:: FilterColor()
437
438    Filter for color calculations
439
440    .. attribute:: matrix
441
442       matrix [4][5] for color calculation
443
444    .. attribute:: previous
445
446       previous pixel filter
447
448 .. class:: FilterGray()
449
450    Filter for gray scale effect
451
452    .. attribute:: previous
453
454       previous pixel filter
455
456 .. class:: FilterLevel()
457
458    Filter for levels calculations
459
460    .. attribute:: levels
461
462       levels matrix [4] (min, max)
463
464    .. attribute:: previous
465
466       previous pixel filter
467
468 .. class:: FilterNormal()
469
470    Filter for Blue Screen objects
471
472    .. attribute:: colorIdx
473
474       index of color used to calculate normal (0 - red, 1 - green, 2 - blue)
475
476    .. attribute:: depth
477
478       depth of relief
479
480    .. attribute:: previous
481
482       previous pixel filter
483
484 .. class:: FilterRGB24()
485
486    Returns a new input filter object to be used with :class:`ImageBuff` object when the image passed
487    to the ImageBuff.load() function has the 3-bytes pixel format BGR.
488
489 .. class:: FilterRGBA32()
490
491    Source filter RGBA32 objects
492
493 .. function:: getLastError()
494
495    Last error that occurred in a bge.texture function.
496
497    :return: the description of the last error occurred in a bge.texture function.
498    :rtype: string
499
500 .. function:: imageToArray(image,mode)
501
502    Returns a :class:`~bgl.buffer` corresponding to the current image stored in a texture source object.
503
504    :arg image: Image source object.
505    :type image: object of type :class:`VideoFFmpeg`, :class:`ImageFFmpeg`, :class:`ImageBuff`, :class:`ImageMix`, :class:`ImageRender`, :class:`ImageMirror` or :class:`ImageViewport`
506    :arg mode: optional argument representing the pixel format.
507       You can use the characters R, G, B for the 3 color channels, A for the alpha channel,
508       0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
509       Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order.
510       "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
511       The default mode is "RGBA".
512
513    :type mode: string
514    :rtype: :class:`~bgl.buffer`
515    :return: A object representing the image as one dimensional array of bytes of size (pixel_size*width*height),
516       line by line starting from the bottom of the image. The pixel size and format is determined by the mode
517       parameter.
518
519 .. function materialID(object,name)
520
521    Returns a numeric value that can be used in :class:`Texture` to create a dynamic texture.
522
523    The value corresponds to an internal material number that uses the texture identified
524    by name. name is a string representing a texture name with IM prefix if you want to
525    identify the texture directly.    This method works for basic tex face and for material,
526    provided the material has a texture channel using that particular texture in first
527    position of the texture stack.    name can also have MA prefix if you want to identify
528    the texture by material. In that case the material must have a texture channel in first
529    position.
530
531    If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
532
533    Ex: bge.texture.materialID(obj, 'IMvideo.png')
534
535    :arg object: the game object that uses the texture you want to make dynamic
536    :type object: game object
537    :arg name: name of the texture/material you want to make dynamic.
538    :type name: string
539    :rtype: integer
540
541 .. function setLogFile(filename)
542
543    Sets the name of a text file in which runtime error messages will be written, in addition to the printing
544    of the messages on the Python console. Only the runtime errors specific to the VideoTexture module
545    are written in that file, ordinary runtime time errors are not written.
546
547    :arg filename: name of error log file
548    :type filename: string
549    :rtype: integer