rst bge touch ups: making the title of the examples slightly more noticeable
[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 .. class:: ImageViewport()
355
356    Image source from viewport
357
358    .. attribute:: alpha
359
360       use alpha in texture
361
362    .. attribute:: capsize
363
364       size of viewport area being captured
365
366    .. attribute:: filter
367
368       pixel filter
369
370    .. attribute:: flip
371
372       flip image vertically
373
374    .. attribute:: image
375
376       image data
377
378    .. attribute:: position
379
380       upper left corner of captured area
381
382    .. method:: refresh(imageViewport)
383
384       Refresh image - invalidate its current content
385
386    .. attribute:: scale
387
388       fast scale of image (near neighbour)
389
390    .. attribute:: size
391
392       image size
393
394    .. attribute:: valid
395
396       bool to tell if an image is available
397
398    .. attribute:: whole
399
400       use whole viewport to capture
401
402 .. class:: Texture(gameObj)
403
404    Texture objects
405
406    .. attribute:: bindId
407
408       OpenGL Bind Name
409
410    .. method:: close(texture)
411
412       Close dynamic texture and restore original
413
414    .. attribute:: mipmap
415
416       mipmap texture
417
418    .. method:: refresh(texture)
419
420       Refresh texture from source
421
422    .. attribute:: source
423
424       source of texture
425
426 .. class:: FilterBGR24()
427
428    Source filter BGR24 objects
429
430 .. class:: FilterBlueScreen()
431
432    Filter for Blue Screen objects
433
434    .. attribute:: color
435
436       blue screen color
437
438    .. attribute:: limits
439
440       blue screen color limits
441
442    .. attribute:: previous
443
444       previous pixel filter
445
446 .. class:: FilterColor()
447
448    Filter for color calculations
449
450    .. attribute:: matrix
451
452       matrix [4][5] for color calculation
453
454    .. attribute:: previous
455
456       previous pixel filter
457
458 .. class:: FilterGray()
459
460    Filter for gray scale effect
461
462    .. attribute:: previous
463
464       previous pixel filter
465
466 .. class:: FilterLevel()
467
468    Filter for levels calculations
469
470    .. attribute:: levels
471
472       levels matrix [4] (min, max)
473
474    .. attribute:: previous
475
476       previous pixel filter
477
478 .. class:: FilterNormal()
479
480    Filter for Blue Screen objects
481
482    .. attribute:: colorIdx
483
484       index of color used to calculate normal (0 - red, 1 - green, 2 - blue)
485
486    .. attribute:: depth
487
488       depth of relief
489
490    .. attribute:: previous
491
492       previous pixel filter
493
494 .. class:: FilterRGB24()
495
496    Returns a new input filter object to be used with :class:`ImageBuff` object when the image passed
497    to the ImageBuff.load() function has the 3-bytes pixel format BGR.
498
499 .. class:: FilterRGBA32()
500
501    Source filter RGBA32 objects
502
503 .. function:: getLastError()
504
505    Last error that occurred in a bge.texture function.
506
507    :return: the description of the last error occurred in a bge.texture function.
508    :rtype: string
509
510 .. function:: imageToArray(image,mode)
511
512    Returns a :class:`~bgl.buffer` corresponding to the current image stored in a texture source object.
513
514    :arg image: Image source object.
515    :type image: object of type :class:`VideoFFmpeg`, :class:`ImageFFmpeg`, :class:`ImageBuff`, :class:`ImageMix`, :class:`ImageRender`, :class:`ImageMirror` or :class:`ImageViewport`
516    :arg mode: optional argument representing the pixel format.
517       You can use the characters R, G, B for the 3 color channels, A for the alpha channel,
518       0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
519       Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order.
520       "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
521       The default mode is "RGBA".
522
523    :type mode: string
524    :rtype: :class:`~bgl.buffer`
525    :return: A object representing the image as one dimensional array of bytes of size (pixel_size*width*height),
526       line by line starting from the bottom of the image. The pixel size and format is determined by the mode
527       parameter.
528
529 .. function:: materialID(object,name)
530
531    Returns a numeric value that can be used in :class:`Texture` to create a dynamic texture.
532
533    The value corresponds to an internal material number that uses the texture identified
534    by name. name is a string representing a texture name with IM prefix if you want to
535    identify the texture directly.    This method works for basic tex face and for material,
536    provided the material has a texture channel using that particular texture in first
537    position of the texture stack.    name can also have MA prefix if you want to identify
538    the texture by material. In that case the material must have a texture channel in first
539    position.
540
541    If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
542
543    Ex: bge.texture.materialID(obj, 'IMvideo.png')
544
545    :arg object: the game object that uses the texture you want to make dynamic
546    :type object: game object
547    :arg name: name of the texture/material you want to make dynamic.
548    :type name: string
549    :rtype: integer
550
551 .. function:: setLogFile(filename)
552
553    Sets the name of a text file in which runtime error messages will be written, in addition to the printing
554    of the messages on the Python console. Only the runtime errors specific to the VideoTexture module
555    are written in that file, ordinary runtime time errors are not written.
556
557    :arg filename: name of error log file
558    :type filename: string
559    :rtype: integer