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