Remove redundant lists, link instead
[blender.git] / doc / python_api / rst / bge.texture.rst
1
2 Video Texture (bge.texture)
3 ===========================
4
5 ************
6 Introduction
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 :class:`~bge.texture.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 .. include:: ../examples/bge.texture.py
40    :start-line: 1
41    :end-line: 5
42    
43 .. literalinclude:: ../examples/bge.texture.py
44    :lines: 7-
45
46 .. include:: ../examples/bge.texture.1.py
47    :start-line: 1
48    :end-line: 6
49    
50 .. literalinclude:: ../examples/bge.texture.1.py
51    :lines: 8-
52    
53    
54 *************
55 Video classes
56 *************
57
58 .. class:: VideoFFmpeg(file, capture=-1, rate=25.0, width=0, height=0)
59
60    FFmpeg video source.
61       
62    :arg file: Path to the video to load; if capture >= 0 on Windows, this parameter will not be used.
63    :type file: str
64    :arg capture: Capture device number; if >= 0, the corresponding webcam will be used. (optional)
65    :type capture: int
66    :arg rate: Capture rate. (optional, used only if capture >= 0)
67    :type rate: float
68    :arg width: Capture width. (optional, used only if capture >= 0)
69    :type width: int
70    :arg height: Capture height. (optional, used only if capture >= 0)
71    :type height: int
72
73    .. attribute:: status
74
75       Video status. (readonly)
76       
77       :type: int
78       :value: see `FFmpeg Video and Image Status`_.
79
80    .. attribute:: range
81
82       Replay range.
83       
84       :type: sequence of two floats
85
86    .. attribute:: repeat
87
88       Repeat count, -1 for infinite repeat.
89
90       :type: int
91
92    .. attribute:: framerate
93
94       Frame rate.
95
96       :type: float
97
98    .. attribute:: valid
99
100       Tells if an image is available. (readonly)
101
102       :type: bool
103
104    .. attribute:: image
105
106       Image data. (readonly)
107       
108       :type: :class:`~bgl.Buffer` or None
109
110    .. attribute:: size
111
112       Image size. (readonly)
113       
114       :type: tuple of two ints
115
116    .. attribute:: scale
117
118       Fast scale of image (near neighbour).
119       
120       :type: bool
121
122    .. attribute:: flip
123
124       Flip image vertically.
125       
126       :type: bool
127
128    .. attribute:: filter
129
130       Pixel filter.
131       
132       :type: one of...
133       
134          * :class:`FilterBGR24`
135          * :class:`FilterBlueScreen`
136          * :class:`FilterColor`
137          * :class:`FilterGray`
138          * :class:`FilterLevel`
139          * :class:`FilterNormal`
140          * :class:`FilterRGB24`
141          * :class:`FilterRGBA32`
142
143    .. attribute:: preseek
144
145       Number of frames of preseek.
146
147       :type: int
148
149    .. attribute:: deinterlace
150
151       Deinterlace image.
152
153       :type: bool
154
155    .. method:: play()
156
157       Play (restart) video.
158       
159       :return: Whether the video was ready or stopped.
160       :rtype: bool
161
162    .. method:: pause()
163
164       Pause video.
165       
166       :return: Whether the video was playing.
167       :rtype: bool
168
169    .. method:: stop()
170
171       Stop video (play will replay it from start).
172       
173       :return: Whether the video was playing.
174       :rtype: bool
175
176    .. method:: refresh()
177
178       Refresh video - get its status.
179       
180       :value: see `FFmpeg Video and Image Status`_.
181
182       :rtype: int
183
184 *************
185 Image classes
186 *************
187
188 .. class:: ImageFFmpeg(file)
189
190    FFmpeg image source.
191       
192    :arg file: Path to the image to load.
193    :type file: str
194
195    .. attribute:: status
196
197       Image status. (readonly)
198       
199       :type: int
200       :value: see `FFmpeg Video and Image Status`_.
201
202    .. attribute:: valid
203
204       Tells if an image is available. (readonly)
205
206       :type: bool
207
208    .. attribute:: image
209
210       Image data. (readonly)
211       
212       :type: :class:`~bgl.Buffer` or None
213
214    .. attribute:: size
215
216       Image size. (readonly)
217       
218       :type: tuple of two ints
219
220    .. attribute:: scale
221
222       Fast scale of image (near neighbour).
223       
224       :type: bool
225
226    .. attribute:: flip
227
228       Flip image vertically.
229       
230       :type: bool
231
232    .. attribute:: filter
233
234       Pixel filter.
235       
236       :type: one of...
237       
238          * :class:`FilterBGR24`
239          * :class:`FilterBlueScreen`
240          * :class:`FilterColor`
241          * :class:`FilterGray`
242          * :class:`FilterLevel`
243          * :class:`FilterNormal`
244          * :class:`FilterRGB24`
245          * :class:`FilterRGBA32`
246
247    .. method:: refresh()
248
249       Refresh image, i.e. load it.
250       
251       :value: see `FFmpeg Video and Image Status`_.
252
253       :rtype: int
254
255    .. method:: reload(newname=None)
256
257       Reload image, i.e. reopen it.
258       
259       :arg newname: Path to a new image. (optional)
260       :type newname: str
261
262 .. class:: ImageBuff(width, height, color=0, scale=False)
263
264    Image source from image buffer.
265    
266    :arg width: Width of the image.
267    :type width: int
268    :arg height: Height of the image.
269    :type height: int
270    :arg color: Value to initialize RGB channels with. The initialized buffer will have
271                all pixels set to (color, color, color, 255). (optional)
272    :type color: int in [0, 255]
273    :arg scale: Image uses scaling. (optional)
274    :type scale: bool
275
276    .. attribute:: filter
277
278       Pixel filter.
279       
280       :type: one of...
281       
282          * :class:`FilterBGR24`
283          * :class:`FilterBlueScreen`
284          * :class:`FilterColor`
285          * :class:`FilterGray`
286          * :class:`FilterLevel`
287          * :class:`FilterNormal`
288          * :class:`FilterRGB24`
289          * :class:`FilterRGBA32`
290
291    .. attribute:: flip
292
293       Flip image vertically.
294       
295       :type: bool
296
297    .. attribute:: image
298
299       Image data. (readonly)
300       
301       :type: :class:`~bgl.Buffer` or None
302
303    .. method:: load(imageBuffer, width, height)
304
305       Load image from buffer.
306       
307       :arg imageBuffer: Buffer to load the image from.
308       :type imageBuffer: :class:`~bgl.Buffer` or Python object implementing the buffer protocol (f.ex. bytes)
309       :arg width: Width of the image to load.
310       :type width: int
311       :arg height: Height of the image to load.
312       :type height: int
313
314    .. method:: plot(imageBuffer, width, height, positionX, positionY, mode=IMB_BLEND_COPY)
315
316       Update image buffer.
317       
318       :arg imageBuffer: Buffer to load the new data from.
319       :type imageBuffer: :class:`~bgl.Buffer`, :class:`ImageBuff` or Python object implementing the buffer protocol (f.ex. bytes)
320       :arg width: Width of the data to load.
321       :type width: int
322       :arg height: Height of the data to load.
323       :type height: int
324       :arg positionX: Left boundary of the region to be drawn on.
325       :type positionX: int
326       :arg positionY: Upper boundary of the region to be drawn on.
327       :type positionY: int
328       :arg mode: Drawing mode, see `Image Blending Modes`_.
329       :type mode: int
330       
331
332    .. attribute:: scale
333
334       Fast scale of image (near neighbour).
335       
336       :type: bool
337
338    .. attribute:: size
339
340       Image size. (readonly)
341       
342       :type: tuple of two ints
343
344    .. attribute:: valid
345
346       Tells if an image is available. (readonly)
347
348       :type: bool
349
350 .. class:: ImageMirror(scene, observer, mirror, material=0)
351
352    Image source from mirror.
353    
354    :arg scene: Scene in which the image has to be taken.
355    :type scene: :class:`~bge.types.KX_Scene`
356    :arg observer: Reference object for the mirror (the object from which the mirror has to be looked at, for example a camera).
357    :type observer: :class:`~bge.types.KX_GameObject`
358    :arg mirror: Object holding the mirror.
359    :type mirror: :class:`~bge.types.KX_GameObject`
360    :arg material: ID of the mirror's material to be used for mirroring. (optional)
361    :type material: int
362
363    .. attribute:: alpha
364
365       Use alpha in texture.
366       
367       :type: bool
368
369    .. attribute:: background
370
371       Background color.
372       
373       :type: int or float list [r, g, b, a] in [0.0, 255.0]
374
375    .. attribute:: capsize
376
377       Size of render area.
378       
379       :type: sequence of two ints
380
381    .. attribute:: clip
382
383       Clipping distance.
384       
385       :type: float in [0.01, 5000.0]
386
387    .. attribute:: filter
388
389       Pixel filter.
390       
391       :type: one of...
392       
393          * :class:`FilterBGR24`
394          * :class:`FilterBlueScreen`
395          * :class:`FilterColor`
396          * :class:`FilterGray`
397          * :class:`FilterLevel`
398          * :class:`FilterNormal`
399          * :class:`FilterRGB24`
400          * :class:`FilterRGBA32`
401
402    .. attribute:: flip
403
404       Flip image vertically.
405       
406       :type: bool
407
408    .. attribute:: image
409
410       Image data. (readonly)
411       
412       :type: :class:`~bgl.Buffer` or None
413
414    .. method:: refresh()
415
416       Refresh image - invalidate its current content.
417
418    .. attribute:: scale
419
420       Fast scale of image (near neighbour).
421       
422       :type: bool
423
424    .. attribute:: size
425
426       Image size (readonly).
427       
428       :type: tuple of two ints
429
430    .. attribute:: valid
431
432       Tells if an image is available. (readonly)
433
434       :type: bool
435
436    .. attribute:: whole
437
438       Use whole viewport to render.
439       
440       :type: bool
441
442 .. class:: ImageMix
443
444    Image mixer.
445
446    .. attribute:: filter
447
448       Pixel filter.
449       
450       :type: one of...
451       
452          * :class:`FilterBGR24`
453          * :class:`FilterBlueScreen`
454          * :class:`FilterColor`
455          * :class:`FilterGray`
456          * :class:`FilterLevel`
457          * :class:`FilterNormal`
458          * :class:`FilterRGB24`
459          * :class:`FilterRGBA32`
460
461    .. attribute:: flip
462
463       Flip image vertically.
464       
465       :type: bool
466
467    .. method:: getSource(id)
468
469       Get image source.
470       
471       :arg id: Identifier of the source to get.
472       :type id: str
473       
474       :return: Image source.
475       :rtype: one of...
476       
477          * :class:`VideoFFmpeg`
478          * :class:`ImageFFmpeg`
479          * :class:`ImageBuff`
480          * :class:`ImageMirror`
481          * :class:`ImageMix`
482          * :class:`ImageRender`
483          * :class:`ImageViewport`
484
485    .. method:: getWeight(id)
486
487       Get image source weight.
488       
489       :arg id: Identifier of the source.
490       :type id: str
491       
492       :return: Weight of the source.
493       :rtype: int
494
495    .. attribute:: image
496
497       Image data. (readonly)
498       
499       :type: :class:`~bgl.Buffer` or None
500
501    .. method:: refresh()
502
503       Refresh image - invalidate its current content.
504
505    .. attribute:: scale
506
507       Fast scale of image (near neighbour).
508       
509       :type: bool
510       
511    .. attribute:: size
512
513       Image size. (readonly)
514       
515       :type: tuple of two ints
516
517    .. method:: setSource(id, image)
518
519       Set image source - all sources must have the same size.
520       
521       :arg id: Identifier of the source to set.
522       :type id: str
523       :arg image: Image source of type...
524       
525          * :class:`VideoFFmpeg`
526          * :class:`ImageFFmpeg`
527          * :class:`ImageBuff`
528          * :class:`ImageMirror`
529          * :class:`ImageMix`
530          * :class:`ImageRender`
531          * :class:`ImageViewport`
532
533    .. method:: setWeight(id, weight)
534
535       Set image source weight - the sum of the weights should be 256 to get full color intensity in the output.
536       
537       :arg id: Identifier of the source.
538       :type id: str
539       :arg weight: Weight of the source.
540       :type weight: int
541
542    .. attribute:: valid
543
544       Tells if an image is available. (readonly)
545
546       :type: bool
547
548 .. class:: ImageRender(scene, camera)
549
550    Image source from render.
551    
552    :arg scene: Scene in which the image has to be taken.
553    :type scene: :class:`~bge.types.KX_Scene`
554    :arg camera: Camera from which the image has to be taken.
555    :type camera: :class:`~bge.types.KX_Camera`
556
557    .. attribute:: alpha
558
559       Use alpha in texture.
560       
561       :type: bool
562
563    .. attribute:: background
564
565       Background color.
566       
567       :type: int or float list [r, g, b, a] in [0.0, 255.0]
568
569    .. attribute:: capsize
570
571       Size of render area.
572       
573       :type: sequence of two ints
574
575    .. attribute:: filter
576
577       Pixel filter.
578       
579       :type: one of...
580       
581          * :class:`FilterBGR24`
582          * :class:`FilterBlueScreen`
583          * :class:`FilterColor`
584          * :class:`FilterGray`
585          * :class:`FilterLevel`
586          * :class:`FilterNormal`
587          * :class:`FilterRGB24`
588          * :class:`FilterRGBA32`
589
590    .. attribute:: flip
591
592       Flip image vertically.
593       
594       :type: bool
595
596    .. attribute:: image
597
598       Image data. (readonly)
599       
600       :type: :class:`~bgl.Buffer` or None
601
602    .. method:: refresh()
603
604       Refresh image - invalidate its current content.
605
606    .. attribute:: scale
607
608       Fast scale of image (near neighbour).
609       
610       :type: bool
611
612    .. attribute:: size
613
614       Image size. (readonly)
615       
616       :type: tuple of two ints
617
618    .. attribute:: valid
619
620       Tells if an image is available. (readonly)
621
622       :type: bool
623
624    .. attribute:: whole
625
626       Use whole viewport to render.
627       
628       :type: bool
629
630    .. attribute:: depth
631
632       Use depth component of render as array of float - not suitable for texture source,
633       should only be used with bge.texture.imageToArray(mode='F').
634       
635       :type: bool
636
637    .. attribute:: zbuff
638
639       Use depth component of render as grey scale color -  suitable for texture source.
640       
641       :type: bool
642
643 .. class:: ImageViewport
644
645    Image source from viewport.
646
647    .. attribute:: alpha
648
649       Use alpha in texture.
650       
651       :type: bool
652
653    .. attribute:: capsize
654
655       Size of viewport area being captured.
656       
657       :type: sequence of two ints
658
659    .. attribute:: filter
660
661       Pixel filter.
662       
663       :type: one of...
664       
665          * :class:`FilterBGR24`
666          * :class:`FilterBlueScreen`
667          * :class:`FilterColor`
668          * :class:`FilterGray`
669          * :class:`FilterLevel`
670          * :class:`FilterNormal`
671          * :class:`FilterRGB24`
672          * :class:`FilterRGBA32`
673
674    .. attribute:: flip
675
676       Flip image vertically.
677       
678       :type: bool
679
680    .. attribute:: image
681
682       Image data. (readonly)
683       
684       :type: :class:`~bgl.Buffer` or None
685
686    .. attribute:: position
687
688       Upper left corner of the captured area.
689       
690       :type: sequence of two ints
691
692    .. method:: refresh()
693
694       Refresh image - invalidate its current content.
695
696    .. attribute:: scale
697
698       Fast scale of image (near neighbour).
699       
700       :type: bool
701
702    .. attribute:: size
703
704       Image size. (readonly)
705       
706       :type: tuple of two ints
707
708    .. attribute:: valid
709
710       Tells if an image is available. (readonly)
711
712       :type: bool
713
714    .. attribute:: whole
715
716       Use whole viewport to capture.
717       
718       :type: bool
719
720    .. attribute:: depth
721
722       Use depth component of viewport as array of float - not suitable for texture source,
723       should only be used with bge.texture.imageToArray(mode='F').
724       
725       :type: bool
726
727    .. attribute:: zbuff
728
729       Use depth component of viewport as grey scale color -  suitable for texture source.
730       
731       :type: bool
732
733    
734 ***************
735 Texture classes
736 ***************
737
738 .. class:: Texture(gameObj, materialID=0, textureID=0, textureObj=None)
739
740    Texture object.
741    
742    :arg gameObj: Game object to be created a video texture on.
743    :type gameObj: :class:`~bge.types.KX_GameObject`
744    :arg materialID: Material ID. (optional)
745    :type materialID: int
746    :arg textureID: Texture ID. (optional)
747    :type textureID: int
748    :arg textureObj: Texture object with shared bindId. (optional)
749    :type textureObj: :class:`Texture`
750
751    .. attribute:: bindId
752
753       OpenGL Bind Name. (readonly)
754       
755       :type: int
756
757    .. method:: close()
758
759       Close dynamic texture and restore original.
760
761    .. attribute:: mipmap
762
763       Mipmap texture.
764       
765       :type: bool
766
767    .. method:: refresh(refresh_source=True, ts=-1.0)
768
769       Refresh texture from source.
770       
771       :arg refresh_source: Whether to also refresh the image source of the texture.
772       :type refresh_source: bool
773       :arg ts: If the texture controls a VideoFFmpeg object:
774                timestamp (in seconds from the start of the movie) of the frame to be loaded; this can be
775                used for video-sound synchonization by passing :attr:`~bge.types.KX_SoundActuator.time` to it. (optional)
776       :type ts: float
777
778    .. attribute:: source
779
780       Source of texture.
781       
782       :type: one of...
783       
784          * :class:`VideoFFmpeg`
785          * :class:`ImageFFmpeg`
786          * :class:`ImageBuff`
787          * :class:`ImageMirror`
788          * :class:`ImageMix`
789          * :class:`ImageRender`
790          * :class:`ImageViewport`
791
792    
793 **************
794 Filter classes
795 **************
796
797
798 .. class:: FilterBGR24
799
800    Source filter BGR24.
801
802 .. class:: FilterBlueScreen
803
804    Filter for Blue Screen. The RGB channels of the color are left unchanged, while the output alpha is obtained as follows:
805    
806    * if the square of the euclidian distance between the RGB color and the filter's reference color is smaller than the filter's lower limit,
807      the output alpha is set to 0;
808    
809    * if that square is bigger than the filter's upper limit, the output alpha is set to 255;
810    
811    * otherwise the output alpha is linarly extrapoled between 0 and 255 in the interval of the limits.
812
813    .. attribute:: color
814
815       Reference color.
816       
817       :type: sequence of three ints
818       :default: (0, 0, 255)
819
820    .. attribute:: limits
821
822       Reference color limits.
823       
824       :type: sequence of two ints
825       :default: (64, 64)
826
827    .. attribute:: previous
828
829       Previous pixel filter.
830       
831       :type: one of...
832       
833          * :class:`FilterBGR24`
834          * :class:`FilterBlueScreen`
835          * :class:`FilterColor`
836          * :class:`FilterGray`
837          * :class:`FilterLevel`
838          * :class:`FilterNormal`
839          * :class:`FilterRGB24`
840          * :class:`FilterRGBA32`
841
842 .. class:: FilterColor
843
844    Filter for color calculations. The output color is obtained by multiplying the reduced 4x4 matrix with the input color
845    and adding the remaining column to the result.
846
847    .. attribute:: matrix
848
849       Matrix [4][5] for color calculation.
850       
851       :type: sequence of four sequences of five ints
852       :default: ((256, 0, 0, 0, 0), (0, 256, 0, 0, 0), (0, 0, 256, 0, 0), (0, 0, 0, 256, 0))
853
854    .. attribute:: previous
855
856       Previous pixel filter.
857       
858       :type: one of...
859       
860          * :class:`FilterBGR24`
861          * :class:`FilterBlueScreen`
862          * :class:`FilterColor`
863          * :class:`FilterGray`
864          * :class:`FilterLevel`
865          * :class:`FilterNormal`
866          * :class:`FilterRGB24`
867          * :class:`FilterRGBA32`
868
869 .. class:: FilterGray
870
871    Filter for gray scale effect. Proportions of R, G and B contributions in the output gray scale are 28:151:77.
872
873    .. attribute:: previous
874
875       Previous pixel filter.
876       
877       :type: one of...
878       
879          * :class:`FilterBGR24`
880          * :class:`FilterBlueScreen`
881          * :class:`FilterColor`
882          * :class:`FilterGray`
883          * :class:`FilterLevel`
884          * :class:`FilterNormal`
885          * :class:`FilterRGB24`
886          * :class:`FilterRGBA32`
887
888 .. class:: FilterLevel
889
890    Filter for levels calculations. Each output color component is obtained as follows:
891    
892    * if it is smaller than its corresponding min value, it is set to 0;
893    
894    * if it is bigger than its corresponding max value, it is set to 255;
895    
896    * Otherwise it is linearly extrapoled between 0 and 255 in the (min, max) interval.
897
898    .. attribute:: levels
899
900       Levels matrix [4] (min, max).
901       
902       :type: sequence of four sequences of two ints
903       :default: ((0, 255), (0, 255), (0, 255), (0, 255))
904
905    .. attribute:: previous
906
907       Previous pixel filter.
908       
909       :type: one of...
910       
911          * :class:`FilterBGR24`
912          * :class:`FilterBlueScreen`
913          * :class:`FilterColor`
914          * :class:`FilterGray`
915          * :class:`FilterLevel`
916          * :class:`FilterNormal`
917          * :class:`FilterRGB24`
918          * :class:`FilterRGBA32`
919
920 .. class:: FilterNormal
921
922    Normal map filter.
923
924    .. attribute:: colorIdx
925
926       Index of color used to calculate normal (0 - red, 1 - green, 2 - blue, 3 - alpha).
927       
928       :type: int in [0, 3]
929       :default: 0
930
931    .. attribute:: depth
932
933       Depth of relief.
934       
935       :type: float
936       :default: 4.0
937
938    .. attribute:: previous
939
940       Previous pixel filter.
941       
942       :type: one of...
943       
944          * :class:`FilterBGR24`
945          * :class:`FilterBlueScreen`
946          * :class:`FilterColor`
947          * :class:`FilterGray`
948          * :class:`FilterLevel`
949          * :class:`FilterNormal`
950          * :class:`FilterRGB24`
951          * :class:`FilterRGBA32`
952
953 .. class:: FilterRGB24
954
955    Returns a new input filter object to be used with :class:`ImageBuff` object when the image passed
956    to the :meth:`ImageBuff.load` function has the 3-bytes pixel format BGR.
957
958 .. class:: FilterRGBA32
959
960    Source filter RGBA32.
961
962
963 *********
964 Functions
965 *********
966
967 .. function:: getLastError()
968
969    Last error that occurred in a bge.texture function.
970
971    :return: The description of the last error occurred in a bge.texture function.
972    :rtype: str
973
974 .. function:: imageToArray(image, mode)
975
976    Returns a :class:`~bgl.Buffer` corresponding to the current image stored in a texture source object.
977
978    :arg image: Image source object of type ...
979
980       * :class:`VideoFFmpeg`
981       * :class:`ImageFFmpeg`
982       * :class:`ImageBuff`
983       * :class:`ImageMirror`
984       * :class:`ImageMix`
985       * :class:`ImageRender`
986       * :class:`ImageViewport`
987    
988    :arg mode: Optional argument representing the pixel format.
989               
990       * You can use the characters R, G, B for the 3 color channels, A for the alpha channel,
991         0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
992         
993         Examples:
994             * "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order.
995             * "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
996       
997       * A special mode "F" allows to return the image as an array of float. This mode should only be used to retrieve
998         the depth buffer of the class:`ImageViewport` and :class:`ImageRender` objects.
999         The default mode is "RGBA".
1000    
1001    :type mode: str
1002    
1003    :return: An object representing the image as one dimensional array of bytes of size (pixel_size*width*height),
1004             line by line starting from the bottom of the image. The pixel size and format is determined by the mode
1005             parameter. For mode 'F', the array is a one dimensional array of float of size (width*height).
1006    :rtype: :class:`~bgl.Buffer`
1007
1008 .. function:: materialID(object, name)
1009
1010    Returns a numeric value that can be used in :class:`Texture` to create a dynamic texture.
1011
1012    The value corresponds to an internal material number that uses the texture identified
1013    by name. name is a string representing a texture name with ``IM`` prefix if you want to
1014    identify the texture directly. This method works for basic tex face and for material,
1015    provided the material has a texture channel using that particular texture in first
1016    position of the texture stack. name can also have ``MA`` prefix if you want to identify
1017    the texture by material. In that case the material must have a texture channel in first
1018    position.
1019
1020    If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
1021
1022    Ex: ``bge.texture.materialID(obj, 'IMvideo.png')``
1023
1024    :arg object: The game object that uses the texture you want to make dynamic.
1025    :type object: :class:`~bge.types.KX_GameObject`
1026    :arg name: Name of the texture/material you want to make dynamic.
1027    :type name: str
1028    
1029    :return: The internal material number.
1030    :rtype: int
1031
1032 .. function:: setLogFile(filename)
1033
1034    Sets the name of a text file in which runtime error messages will be written, in addition to the printing
1035    of the messages on the Python console. Only the runtime errors specific to the VideoTexture module
1036    are written in that file, ordinary runtime time errors are not written.
1037
1038    :arg filename: Name of the error log file.
1039    :type filename: str
1040    
1041    :return: -1 if the parameter name is invalid (not of type string), else 0.
1042    :rtype: int
1043
1044    
1045 *********
1046 Constants
1047 *********
1048
1049 FFmpeg Video and Image Status
1050 +++++++++++++++++++++++++++++
1051
1052
1053 .. data:: SOURCE_ERROR
1054
1055 .. data:: SOURCE_EMPTY
1056
1057 .. data:: SOURCE_READY
1058
1059 .. data:: SOURCE_PLAYING
1060
1061 .. data:: SOURCE_STOPPED
1062
1063
1064 Image Blending Modes
1065 ++++++++++++++++++++
1066
1067 See Wikipedia's `Blend Modes <https://en.wikipedia.org/wiki/Blend_modes>`_ for reference.
1068
1069 .. data:: IMB_BLEND_MIX
1070
1071 .. data:: IMB_BLEND_ADD
1072
1073 .. data:: IMB_BLEND_SUB
1074
1075 .. data:: IMB_BLEND_MUL
1076
1077 .. data:: IMB_BLEND_LIGHTEN
1078
1079 .. data:: IMB_BLEND_DARKEN
1080
1081 .. data:: IMB_BLEND_ERASE_ALPHA
1082
1083 .. data:: IMB_BLEND_ADD_ALPHA
1084
1085 .. data:: IMB_BLEND_OVERLAY
1086
1087 .. data:: IMB_BLEND_HARDLIGHT
1088
1089 .. data:: IMB_BLEND_COLORBURN
1090
1091 .. data:: IMB_BLEND_LINEARBURN
1092
1093 .. data:: IMB_BLEND_COLORDODGE
1094
1095 .. data:: IMB_BLEND_SCREEN
1096
1097 .. data:: IMB_BLEND_SOFTLIGHT
1098
1099 .. data:: IMB_BLEND_PINLIGHT
1100
1101 .. data:: IMB_BLEND_VIVIDLIGHT
1102
1103 .. data:: IMB_BLEND_LINEARLIGHT
1104
1105 .. data:: IMB_BLEND_DIFFERENCE
1106
1107 .. data:: IMB_BLEND_EXCLUSION
1108
1109 .. data:: IMB_BLEND_HUE
1110
1111 .. data:: IMB_BLEND_SATURATION
1112
1113 .. data:: IMB_BLEND_LUMINOSITY
1114
1115 .. data:: IMB_BLEND_COLOR
1116
1117 .. data:: IMB_BLEND_COPY
1118
1119 .. data:: IMB_BLEND_COPY_RGB
1120
1121 .. data:: IMB_BLEND_COPY_ALPHA
1122