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