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