T48694: fix bge.texture.Texture.refresh() documentation
[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,
12 camera render or a mix of that.
13
14 The video and image files can be loaded from the internet using an URL instead of a file name.
15
16 In addition, you can apply filters on the images before sending them to the GPU, allowing video effect:
17 blue screen, color band, gray, normal map.
18
19 bge.texture uses FFmpeg to load images and videos.
20 All the formats and codecs that FFmpeg supports are supported by this module, including but not limited to:
21
22 * AVI
23 * Ogg
24 * Xvid
25 * Theora
26 * dv1394 camera
27 * video4linux capture card (this includes many webcams)
28 * videoForWindows capture card (this includes many webcams)
29 * JPG
30
31 The principle is simple: first you identify a texture on an existing object using
32 the :class:`~bge.texture.materialID` function, then you create a new texture with dynamic content
33 and swap the two textures in the GPU.
34
35 The GE is not aware of the substitution and continues to display the object as always,
36 except that you are now in control of the texture.
37
38 When the texture object is deleted, the new texture is deleted and the old texture restored.
39
40 .. module:: bge.texture
41
42 .. include:: __/examples/bge.texture.py
43    :start-line: 1
44    :end-line: 5
45
46 .. literalinclude:: __/examples/bge.texture.py
47    :lines: 7-
48
49 .. include:: __/examples/bge.texture.1.py
50    :start-line: 1
51    :end-line: 6
52
53 .. literalinclude:: __/examples/bge.texture.1.py
54    :lines: 8-
55
56
57 .. include:: __/examples/bge.texture.2.py
58    :start-line: 1
59    :end-line: 6
60
61 .. literalinclude:: __/examples/bge.texture.2.py
62    :lines: 8-
63
64
65 *************
66 Video classes
67 *************
68
69 .. class:: VideoFFmpeg(file, capture=-1, rate=25.0, width=0, height=0)
70
71    FFmpeg video source.
72
73    :arg file: Path to the video to load; if capture >= 0 on Windows, this parameter will not be used.
74    :type file: str
75    :arg capture: Capture device number; if >= 0, the corresponding webcam will be used. (optional)
76    :type capture: int
77    :arg rate: Capture rate. (optional, used only if capture >= 0)
78    :type rate: float
79    :arg width: Capture width. (optional, used only if capture >= 0)
80    :type width: int
81    :arg height: Capture height. (optional, used only if capture >= 0)
82    :type height: int
83
84    .. attribute:: status
85
86       Video status. (readonly)
87
88       :type: int
89       :value: see `FFmpeg Video and Image Status`_.
90
91    .. attribute:: range
92
93       Replay range.
94
95       :type: sequence of two floats
96
97    .. attribute:: repeat
98
99       Repeat count, -1 for infinite repeat.
100
101       :type: int
102
103    .. attribute:: framerate
104
105       Frame rate.
106
107       :type: float
108
109    .. attribute:: valid
110
111       Tells if an image is available. (readonly)
112
113       :type: bool
114
115    .. attribute:: image
116
117       Image data. (readonly)
118
119       :type: :class:`~bgl.Buffer` or None
120
121    .. attribute:: size
122
123       Image size. (readonly)
124
125       :type: tuple of two ints
126
127    .. attribute:: scale
128
129       Fast scale of image (near neighbour).
130
131       :type: bool
132
133    .. attribute:: flip
134
135       Flip image vertically.
136
137       :type: bool
138
139    .. attribute:: filter
140
141       Pixel filter.
142
143       :type: one of...
144
145          * :class:`FilterBGR24`
146          * :class:`FilterBlueScreen`
147          * :class:`FilterColor`
148          * :class:`FilterGray`
149          * :class:`FilterLevel`
150          * :class:`FilterNormal`
151          * :class:`FilterRGB24`
152          * :class:`FilterRGBA32`
153
154    .. attribute:: preseek
155
156       Number of frames of preseek.
157
158       :type: int
159
160    .. attribute:: deinterlace
161
162       Deinterlace image.
163
164       :type: bool
165
166    .. method:: play()
167
168       Play (restart) video.
169
170       :return: Whether the video was ready or stopped.
171       :rtype: bool
172
173    .. method:: pause()
174
175       Pause video.
176
177       :return: Whether the video was playing.
178       :rtype: bool
179
180    .. method:: stop()
181
182       Stop video (play will replay it from start).
183
184       :return: Whether the video was playing.
185       :rtype: bool
186
187    .. method:: refresh(buffer=None, format="RGBA", timestamp=-1.0)
188
189       Refresh video - get its status and optionally copy the frame to an external buffer.
190
191       :arg buffer: An optional object that implements the buffer protocol.
192          If specified, the image is copied to the buffer, which must be big enough or an exception is thrown.
193       :type buffer: any buffer type
194       :arg format: An optional image format specifier for the image that will be copied to the buffer.
195          Only valid values are "RGBA" or "BGRA"
196       :type format: str
197       :arg timestamp: An optional timestamp (in seconds from the start of the movie)
198          of the frame to be copied to the buffer.
199       :type timestamp: float
200       :return: see `FFmpeg Video and Image Status`_.
201       :rtype: int
202
203
204 *************
205 Image classes
206 *************
207
208 .. class:: ImageFFmpeg(file)
209
210    FFmpeg image source.
211
212    :arg file: Path to the image to load.
213    :type file: str
214
215    .. attribute:: status
216
217       Image status. (readonly)
218
219       :type: int
220       :value: see `FFmpeg Video and Image Status`_.
221
222    .. attribute:: valid
223
224       Tells if an image is available. (readonly)
225
226       :type: bool
227
228    .. attribute:: image
229
230       Image data. (readonly)
231
232       :type: :class:`~bgl.Buffer` or None
233
234    .. attribute:: size
235
236       Image size. (readonly)
237
238       :type: tuple of two ints
239
240    .. attribute:: scale
241
242       Fast scale of image (near neighbour).
243
244       :type: bool
245
246    .. attribute:: flip
247
248       Flip image vertically.
249
250       :type: bool
251
252    .. attribute:: filter
253
254       Pixel filter.
255
256       :type: one of...
257
258          * :class:`FilterBGR24`
259          * :class:`FilterBlueScreen`
260          * :class:`FilterColor`
261          * :class:`FilterGray`
262          * :class:`FilterLevel`
263          * :class:`FilterNormal`
264          * :class:`FilterRGB24`
265          * :class:`FilterRGBA32`
266
267    .. method:: refresh(buffer=None, format="RGBA")
268
269       Refresh image, get its status and optionally copy the frame to an external buffer.
270
271       :arg buffer: An optional object that implements the buffer protocol.
272          If specified, the image is copied to the buffer, which must be big enough or an exception is thrown.
273       :type buffer: any buffer type
274       :arg format: An optional image format specifier for the image that will be copied to the buffer.
275          Only valid values are "RGBA" or "BGRA"
276       :type format: str
277       :return: see `FFmpeg Video and Image Status`_.
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`
345          or Python object implementing the buffer protocol (f.ex. bytes)
346       :arg width: Width of the data to load.
347       :type width: int
348       :arg height: Height of the data to load.
349       :type height: int
350       :arg positionX: Left boundary of the region to be drawn on.
351       :type positionX: int
352       :arg positionY: Upper boundary of the region to be drawn on.
353       :type positionY: int
354       :arg mode: Drawing mode, see `Image Blending Modes`_.
355       :type mode: int
356
357
358    .. attribute:: scale
359
360       Fast scale of image (near neighbour).
361
362       :type: bool
363
364    .. attribute:: size
365
366       Image size. (readonly)
367
368       :type: tuple of two ints
369
370    .. attribute:: valid
371
372       Tells if an image is available. (readonly)
373
374       :type: bool
375
376 .. class:: ImageMirror(scene, observer, mirror, material=0)
377
378    Image source from mirror.
379
380    :arg scene: Scene in which the image has to be taken.
381    :type scene: :class:`~bge.types.KX_Scene`
382    :arg observer: Reference object for the mirror
383       (the object from which the mirror has to be looked at, for example a camera).
384    :type observer: :class:`~bge.types.KX_GameObject`
385    :arg mirror: Object holding the mirror.
386    :type mirror: :class:`~bge.types.KX_GameObject`
387    :arg material: ID of the mirror's material to be used for mirroring. (optional)
388    :type material: int
389
390    .. attribute:: alpha
391
392       Use alpha in texture.
393
394       :type: bool
395
396    .. attribute:: background
397
398       Background color.
399
400       :type: int or float list [r, g, b, a] in [0.0, 255.0]
401
402    .. attribute:: capsize
403
404       Size of render area.
405
406       :type: sequence of two ints
407
408    .. attribute:: clip
409
410       Clipping distance.
411
412       :type: float in [0.01, 5000.0]
413
414    .. attribute:: filter
415
416       Pixel filter.
417
418       :type: one of...
419
420          * :class:`FilterBGR24`
421          * :class:`FilterBlueScreen`
422          * :class:`FilterColor`
423          * :class:`FilterGray`
424          * :class:`FilterLevel`
425          * :class:`FilterNormal`
426          * :class:`FilterRGB24`
427          * :class:`FilterRGBA32`
428
429    .. attribute:: flip
430
431       Flip image vertically.
432
433       :type: bool
434
435    .. attribute:: image
436
437       Image data. (readonly)
438
439       :type: :class:`~bgl.Buffer` or None
440
441    .. method:: refresh(buffer=None, format="RGBA")
442
443       Refresh image - render and copy the image to an external buffer (optional)
444       then invalidate its current content.
445
446       :arg buffer: An optional object that implements the buffer protocol.
447          If specified, the image is rendered and copied to the buffer,
448          which must be big enough or an exception is thrown.
449       :type buffer: any buffer type
450       :arg format: An optional image format specifier for the image that will be copied to the buffer.
451          Only valid values are "RGBA" or "BGRA"
452       :type format: str
453
454    .. attribute:: scale
455
456       Fast scale of image (near neighbour).
457
458       :type: bool
459
460    .. attribute:: size
461
462       Image size (readonly).
463
464       :type: tuple of two ints
465
466    .. attribute:: valid
467
468       Tells if an image is available. (readonly)
469
470       :type: bool
471
472    .. attribute:: whole
473
474       Use whole viewport to render.
475
476       :type: bool
477
478 .. class:: ImageMix
479
480    Image mixer.
481
482    .. attribute:: filter
483
484       Pixel filter.
485
486       :type: one of...
487
488          * :class:`FilterBGR24`
489          * :class:`FilterBlueScreen`
490          * :class:`FilterColor`
491          * :class:`FilterGray`
492          * :class:`FilterLevel`
493          * :class:`FilterNormal`
494          * :class:`FilterRGB24`
495          * :class:`FilterRGBA32`
496
497    .. attribute:: flip
498
499       Flip image vertically.
500
501       :type: bool
502
503    .. method:: getSource(id)
504
505       Get image source.
506
507       :arg id: Identifier of the source to get.
508       :type id: str
509
510       :return: Image source.
511       :rtype: one of...
512
513          * :class:`VideoFFmpeg`
514          * :class:`ImageFFmpeg`
515          * :class:`ImageBuff`
516          * :class:`ImageMirror`
517          * :class:`ImageMix`
518          * :class:`ImageRender`
519          * :class:`ImageViewport`
520
521    .. method:: getWeight(id)
522
523       Get image source weight.
524
525       :arg id: Identifier of the source.
526       :type id: str
527
528       :return: Weight of the source.
529       :rtype: int
530
531    .. attribute:: image
532
533       Image data. (readonly)
534
535       :type: :class:`~bgl.Buffer` or None
536
537    .. method:: refresh(buffer=None, format="RGBA")
538
539       Refresh image - calculate and copy the image to an external buffer (optional)
540       then invalidate its current content.
541
542       :arg buffer: An optional object that implements the buffer protocol.
543          If specified, the image is calculated and copied to the buffer,
544          which must be big enough or an exception is thrown.
545       :type buffer: any buffer type
546       :arg format: An optional image format specifier for the image that will be copied to the buffer.
547          Only valid values are "RGBA" or "BGRA"
548       :type format: str
549
550    .. attribute:: scale
551
552       Fast scale of image (near neighbour).
553
554       :type: bool
555
556    .. attribute:: size
557
558       Image size. (readonly)
559
560       :type: tuple of two ints
561
562    .. method:: setSource(id, image)
563
564       Set image source - all sources must have the same size.
565
566       :arg id: Identifier of the source to set.
567       :type id: str
568       :arg image: Image source of type...
569
570          * :class:`VideoFFmpeg`
571          * :class:`ImageFFmpeg`
572          * :class:`ImageBuff`
573          * :class:`ImageMirror`
574          * :class:`ImageMix`
575          * :class:`ImageRender`
576          * :class:`ImageViewport`
577
578    .. method:: setWeight(id, weight)
579
580       Set image source weight - the sum of the weights should be 256 to get full color intensity in the output.
581
582       :arg id: Identifier of the source.
583       :type id: str
584       :arg weight: Weight of the source.
585       :type weight: int
586
587    .. attribute:: valid
588
589       Tells if an image is available. (readonly)
590
591       :type: bool
592
593 .. class:: ImageRender(scene, camera)
594
595    Image source from render.
596    The render is done on a custom framebuffer object if fbo is specified,
597    otherwise on the default framebuffer.
598
599    :arg scene: Scene in which the image has to be taken.
600    :type scene: :class:`~bge.types.KX_Scene`
601    :arg camera: Camera from which the image has to be taken.
602    :type camera: :class:`~bge.types.KX_Camera`
603    :arg fbo: Off-screen render buffer object (optional)
604    :type fbo: :class:`~bge.render.RASOffScreen`
605
606    .. attribute:: alpha
607
608       Use alpha in texture.
609
610       :type: bool
611
612    .. attribute:: background
613
614       Background color.
615
616       :type: int or float list [r, g, b, a] in [0.0, 255.0]
617
618    .. attribute:: capsize
619
620       Size of render area.
621
622       :type: sequence of two ints
623
624    .. attribute:: filter
625
626       Pixel filter.
627
628       :type: one of...
629
630          * :class:`FilterBGR24`
631          * :class:`FilterBlueScreen`
632          * :class:`FilterColor`
633          * :class:`FilterGray`
634          * :class:`FilterLevel`
635          * :class:`FilterNormal`
636          * :class:`FilterRGB24`
637          * :class:`FilterRGBA32`
638
639    .. attribute:: flip
640
641       Flip image vertically.
642
643       :type: bool
644
645    .. attribute:: image
646
647       Image data. (readonly)
648
649       :type: :class:`~bgl.Buffer` or None
650
651    .. attribute:: scale
652
653       Fast scale of image (near neighbour).
654
655       :type: bool
656
657    .. attribute:: size
658
659       Image size. (readonly)
660
661       :type: tuple of two ints
662
663    .. attribute:: valid
664
665       Tells if an image is available. (readonly)
666
667       :type: bool
668
669    .. attribute:: whole
670
671       Use whole viewport to render.
672
673       :type: bool
674
675    .. attribute:: depth
676
677       Use depth component of render as array of float - not suitable for texture source,
678       should only be used with bge.texture.imageToArray(mode='F').
679
680       :type: bool
681
682    .. attribute:: zbuff
683
684       Use depth component of render as grey scale color -  suitable for texture source.
685
686       :type: bool
687
688    .. method:: render()
689
690       Render the scene but do not extract the pixels yet.
691       The function returns as soon as the render commands have been send to the GPU.
692       The render will proceed asynchronously in the GPU while the host can perform other tasks.
693       To complete the render, you can either call :func:`refresh`
694       directly of refresh the texture of which this object is the source.
695       This method is useful to implement asynchronous render for optimal performance: call render()
696       on frame n and refresh() on frame n+1 to give as much as time as possible to the GPU
697       to render the frame while the game engine can perform other tasks.
698
699       :return: True if the render was initiated, False if the render cannot be performed (e.g. the camera is active)
700       :rtype: bool
701
702    .. method:: refresh()
703    .. method:: refresh(buffer, format="RGBA")
704
705       Refresh video - render and optionally copy the image to an external buffer then invalidate its current content.
706       The render may have been started earlier with the :func:`render` method,
707       in which case this function simply waits for the render operations to complete.
708       When called without argument, the pixels are not extracted but the render is guaranteed
709       to be completed when the function returns.
710       This only makes sense with offscreen render on texture target (see :func:`~bge.render.offScreenCreate`).
711
712       :arg buffer: An object that implements the buffer protocol.
713          If specified, the image is copied to the buffer, which must be big enough or an exception is thrown.
714          The transfer to the buffer is optimal if no processing of the image is needed.
715          This is the case if ``flip=False, alpha=True, scale=False, whole=True, depth=False, zbuff=False``
716          and no filter is set.
717       :type buffer: any buffer type of sufficient size
718       :arg format: An optional image format specifier for the image that will be copied to the buffer.
719          Only valid values are "RGBA" or "BGRA"
720       :type format: str
721       :return: True if the render is complete, False if the render cannot be performed (e.g. the camera is active)
722       :rtype: bool
723
724 .. class:: ImageViewport
725
726    Image source from viewport.
727
728    .. attribute:: alpha
729
730       Use alpha in texture.
731
732       :type: bool
733
734    .. attribute:: capsize
735
736       Size of viewport area being captured.
737
738       :type: sequence of two ints
739
740    .. attribute:: filter
741
742       Pixel filter.
743
744       :type: one of...
745
746          * :class:`FilterBGR24`
747          * :class:`FilterBlueScreen`
748          * :class:`FilterColor`
749          * :class:`FilterGray`
750          * :class:`FilterLevel`
751          * :class:`FilterNormal`
752          * :class:`FilterRGB24`
753          * :class:`FilterRGBA32`
754
755    .. attribute:: flip
756
757       Flip image vertically.
758
759       :type: bool
760
761    .. attribute:: image
762
763       Image data. (readonly)
764
765       :type: :class:`~bgl.Buffer` or None
766
767    .. attribute:: position
768
769       Upper left corner of the captured area.
770
771       :type: sequence of two ints
772
773    .. method:: refresh(buffer=None, format="RGBA")
774
775       Refresh video - copy the viewport to an external buffer (optional) then invalidate its current content.
776
777       :arg buffer: An optional object that implements the buffer protocol.
778          If specified, the image is copied to the buffer, which must be big enough or an exception is thrown.
779          The transfer to the buffer is optimal if no processing of the image is needed.
780          This is the case if ``flip=False, alpha=True, scale=False, whole=True, depth=False, zbuff=False``
781          and no filter is set.
782       :type buffer: any buffer type
783       :arg format: An optional image format specifier for the image that will be copied to the buffer.
784          Only valid values are "RGBA" or "BGRA"
785       :type format: str
786
787    .. attribute:: scale
788
789       Fast scale of image (near neighbour).
790
791       :type: bool
792
793    .. attribute:: size
794
795       Image size. (readonly)
796
797       :type: tuple of two ints
798
799    .. attribute:: valid
800
801       Tells if an image is available. (readonly)
802
803       :type: bool
804
805    .. attribute:: whole
806
807       Use whole viewport to capture.
808
809       :type: bool
810
811    .. attribute:: depth
812
813       Use depth component of viewport as array of float - not suitable for texture source,
814       should only be used with ``bge.texture.imageToArray(mode='F')``.
815
816       :type: bool
817
818    .. attribute:: zbuff
819
820       Use depth component of viewport as grey scale color - suitable for texture source.
821
822       :type: bool
823
824 .. class:: VideoDeckLink(format, capture=0)
825
826    Image source from an external video stream captured with a DeckLink video card from
827    Black Magic Design.
828    Before this source can be used, a DeckLink hardware device must be installed, it can be a PCIe card
829    or a USB device, and the 'Desktop Video' software package (version 10.4 or above must be installed)
830    on the host as described in the DeckLink documentation.
831    If in addition you have a recent nVideo Quadro card, you can benefit from the 'GPUDirect' technology
832    to push the captured video frame very efficiently to the GPU. For this you need to install the
833    'DeckLink SDK' version 10.4 or above and copy the 'dvp.dll' runtime library to Blender's
834    installation directory or to any other place where Blender can load a DLL from.
835
836    :arg format: string describing the video format to be captured.
837    :type format: str
838    :arg capture: Card number from which the input video must be captured.
839    :type capture: int
840
841    The format argument must be written as ``<displayMode>/<pixelFormat>[/3D][:<cacheSize>]`` where ``<displayMode>``
842    describes the frame size and rate and <pixelFormat> the encoding of the pixels.
843    The optional ``/3D`` suffix is to be used if the video stream is stereo with a left and right eye feed.
844    The optional ``:<cacheSize>`` suffix determines the number of the video frames kept in cache, by default 8.
845    Some DeckLink cards won't work below a certain cache size.
846    The default value 8 should be sufficient for all cards.
847    You may try to reduce the cache size to reduce the memory footprint. For example the The 4K Extreme is known
848    to work with 3 frames only, the Extreme 2 needs 4 frames and the Intensity Shuttle needs 6 frames, etc.
849    Reducing the cache size may be useful when Decklink is used in conjunction with GPUDirect:
850    all frames must be locked in memory in that case and that puts a lot of pressure on memory.
851    If you reduce the cache size too much,
852    you'll get no error but no video feed either.
853
854    The valid ``<displayMode>`` values are copied from the ``BMDDisplayMode`` enum in the DeckLink API
855    without the 'bmdMode' prefix. In case a mode that is not in this list is added in a later version
856    of the SDK, it is also possible to specify the 4 letters of the internal code for that mode.
857    You will find the internal code in the ``DeckLinkAPIModes.h`` file that is part of the SDK.
858    Here is for reference the full list of supported display modes with their equivalent internal code:
859
860    Internal Codes
861       - NTSC 'ntsc'
862       - NTSC2398        'nt23'
863       - PAL             'pal '
864       - NTSCp           'ntsp'
865       - PALp            'palp'
866    HD 1080 Modes
867       - HD1080p2398     '23ps'
868       - HD1080p24       '24ps'
869       - HD1080p25       'Hp25'
870       - HD1080p2997     'Hp29'
871       - HD1080p30       'Hp30'
872       - HD1080i50       'Hi50'
873       - HD1080i5994     'Hi59'
874       - HD1080i6000     'Hi60'
875       - HD1080p50       'Hp50'
876       - HD1080p5994     'Hp59'
877       - HD1080p6000     'Hp60'
878    HD 720 Modes
879       - HD720p50        'hp50'
880       - HD720p5994      'hp59'
881       - HD720p60        'hp60'
882    2k Modes
883       - 2k2398  '2k23'
884       - 2k24            '2k24'
885       - 2k25            '2k25'
886    4k Modes
887       - 4K2160p2398     '4k23'
888       - 4K2160p24       '4k24'
889       - 4K2160p25       '4k25'
890       - 4K2160p2997     '4k29'
891       - 4K2160p30       '4k30'
892       - 4K2160p50       '4k50'
893       - 4K2160p5994     '4k59'
894       - 4K2160p60       '4k60'
895
896    Most of names are self explanatory. If necessary refer to the DeckLink API documentation for more information.
897
898    Similarly, <pixelFormat> is copied from the BMDPixelFormat enum.
899
900    Here is for reference the full list of supported pixel format and their equivalent internal code:
901
902    Pixel Formats
903       - 8BitYUV '2vuy'
904       - 10BitYUV        'v210'
905       - 8BitARGB        * no equivalent code *
906       - 8BitBGRA        'BGRA'
907       - 10BitRGB        'r210'
908       - 12BitRGB        'R12B'
909       - 12BitRGBLE      'R12L'
910       - 10BitRGBXLE     'R10l'
911       - 10BitRGBX       'R10b'
912
913    Refer to the DeckLink SDK documentation for a full description of these pixel format.
914    It is important to understand them as the decoding of the pixels is NOT done in VideoTexture
915    for performance reason. Instead a specific shader must be used to decode the pixel in the GPU.
916    Only the '8BitARGB', '8BitBGRA' and '10BitRGBXLE' pixel formats are mapped directly to OpenGL RGB float textures.
917    The '8BitYUV' and '10BitYUV' pixel formats are mapped to openGL RGB float texture but require a shader to decode.
918    The other pixel formats are sent as a ``GL_RED_INTEGER`` texture (i.e. a texture with only the
919    red channel coded as an unsigned 32 bit integer) and are not recommended for use.
920
921    Example: ``HD1080p24/10BitYUV/3D:4`` is equivalent to ``24ps/v210/3D:4``
922    and represents a full HD stereo feed at 24 frame per second and 4 frames cache size.
923
924    Although video format auto detection is possible with certain DeckLink devices, the corresponding
925    API is NOT implemented in the BGE. Therefore it is important to specify the format string that
926    matches exactly the video feed. If the format is wrong, no frame will be captured.
927    It should be noted that the pixel format that you need to specify is not necessarily the actual
928    format in the video feed. For example, the 4K Extreme card delivers 8bit RGBs pixels in the
929    '10BitRGBXLE' format. Use the 'Media Express' application included in 'Desktop Video' to discover
930    which pixel format works for a particular video stream.
931
932    .. attribute:: status
933
934       Status of the capture: 1=ready to use, 2=capturing, 3=stopped
935
936       :type: int
937
938    .. attribute:: framerate
939
940       Capture frame rate as computed from the video format.
941
942       :type: float
943
944    .. attribute:: valid
945
946       Tells if the image attribute can be used to retrieve the image.
947       Always False in this implementation (the image is not available at python level)
948
949       :type: bool
950
951    .. attribute:: image
952
953       The image data. Always None in this implementation.
954
955       :type: :class:`~bgl.Buffer` or None
956
957    .. attribute:: size
958
959       The size of the frame in pixel.
960       Stereo frames have double the height of the video frame, i.e. 3D is delivered to the GPU
961       as a single image in top-bottom order, left eye on top.
962
963       :type: (int,int)
964
965    .. attribute:: scale
966
967       Not used in this object.
968
969       :type: bool
970
971    .. attribute:: flip
972
973       Not used in this object.
974
975       :type: bool
976
977    .. attribute:: filter
978
979       Not used in this object.
980
981    .. method:: play()
982
983       Kick-off the capture after creation of the object.
984
985       :return: True if the capture could be started, False otherwise.
986       :rtype: bool
987
988    .. method:: pause()
989
990       Temporary stops the capture. Use play() to restart it.
991
992       :return: True if the capture could be paused, False otherwise.
993       :rtype: bool
994
995    .. method:: stop()
996
997       Stops the capture.
998
999       :return: True if the capture could be stopped, False otherwise.
1000       :rtype: bool
1001
1002
1003 ***************
1004 Texture classes
1005 ***************
1006
1007 .. class:: Texture(gameObj, materialID=0, textureID=0, textureObj=None)
1008
1009    Texture object.
1010
1011    :arg gameObj: Game object to be created a video texture on.
1012    :type gameObj: :class:`~bge.types.KX_GameObject`
1013    :arg materialID: Material ID. (optional)
1014    :type materialID: int
1015    :arg textureID: Texture ID. (optional)
1016    :type textureID: int
1017    :arg textureObj: Texture object with shared bindId. (optional)
1018    :type textureObj: :class:`Texture`
1019
1020    .. attribute:: bindId
1021
1022       OpenGL Bind Name. (readonly)
1023
1024       :type: int
1025
1026    .. method:: close()
1027
1028       Close dynamic texture and restore original.
1029
1030    .. attribute:: mipmap
1031
1032       Mipmap texture.
1033
1034       :type: bool
1035
1036    .. method:: refresh(refresh_source, timestamp=-1.0)
1037
1038       Refresh texture from source.
1039
1040       :arg refresh_source: Whether to also refresh the image source of the texture.
1041       :type refresh_source: bool
1042       :arg timestamp: If the texture controls a VideoFFmpeg object:
1043          timestamp (in seconds from the start of the movie) of the frame to be loaded; this can be
1044          used for video-sound synchonization by passing :attr:`~bge.types.KX_SoundActuator.time` to it. (optional)
1045       :type timestamp: float
1046
1047    .. attribute:: source
1048
1049       Source of texture.
1050
1051       :type: one of...
1052
1053          * :class:`VideoFFmpeg`
1054          * :class:`VideoDeckLink`
1055          * :class:`ImageFFmpeg`
1056          * :class:`ImageBuff`
1057          * :class:`ImageMirror`
1058          * :class:`ImageMix`
1059          * :class:`ImageRender`
1060          * :class:`ImageViewport`
1061
1062 .. class:: DeckLink(cardIdx=0, format="")
1063
1064    Certain DeckLink devices can be used to playback video: the host sends video frames regularly
1065    for immediate or scheduled playback. The video feed is outputted on HDMI or SDI interfaces.
1066    This class supports the immediate playback mode: it has a source attribute that is assigned
1067    one of the source object in the bge.texture module. Refreshing the DeckLink object causes
1068    the image source to be computed and sent to the DeckLink device for immediate transmission
1069    on the output interfaces.  Keying is supported: it allows to composite the frame with an
1070    input video feed that transits through the DeckLink card.
1071
1072    :arg cardIdx: Number of the card to be used for output (0=first card).
1073       It should be noted that DeckLink devices are usually half duplex:
1074       they can either be used for capture or playback but not both at the same time.
1075    :type cardIdx: int
1076    :arg format: String representing the display mode of the output feed.
1077    :type format: str
1078
1079    The default value of the format argument is reserved for auto detection but it is currently
1080    not supported (it will generate a runtime error) and thus the video format must be explicitly
1081    specified. If keying is the goal (see keying attributes), the format must match exactly the
1082    input video feed, otherwise it can be any format supported by the device (there will be a
1083    runtime error if not).
1084    The format of the string is ``<displayMode>[/3D]``.
1085
1086    Refer to :class:`VideoDeckLink` to get the list of acceptable ``<displayMode>``.
1087    The optional ``/3D`` suffix is used to create a stereo 3D feed.
1088    In that case the 'right' attribute must also be set to specify the image source for the right eye.
1089
1090    Note: The pixel format is not specified here because it is always BGRA. The alpha channel is
1091    used in keying to mix the source with the input video feed, otherwise it is not used.
1092    If a conversion is needed to match the native video format, it is done inside the DeckLink driver
1093    or device.
1094
1095    .. attribute:: source
1096
1097       This attribute must be set to one of the image source. If the image size does not fit exactly
1098       the frame size, the extend attribute determines what to do.
1099
1100       For best performance, the source image should match exactly the size of the output frame.
1101       A further optimization is achieved if the image source object is ImageViewport or ImageRender
1102       set for whole viewport, flip disabled and no filter: the GL frame buffer is copied directly
1103       to the image buffer and directly from there to the DeckLink card (hence no buffer to buffer
1104       copy inside VideoTexture).
1105
1106       :type: one of...
1107          - :class:`VideoFFmpeg`
1108          - :class:`VideoDeckLink`
1109          - :class:`ImageFFmpeg`
1110          - :class:`ImageBuff`
1111          - :class:`ImageMirror`
1112          - :class:`ImageMix`
1113          - :class:`ImageRender`
1114          - :class:`ImageViewport`
1115
1116    .. attribute:: right
1117
1118       If the video format is stereo 3D, this attribute should be set to an image source object
1119       that will produce the right eye images.  If the goal is to render the BGE scene in 3D,
1120       it can be achieved with 2 cameras, one for each eye, used by 2 ImageRender with an offscreen
1121       render buffer that is just the size of the video frame.
1122
1123       :type: one of...
1124          - :class:`VideoFFmpeg`
1125          - :class:`VideoDeckLink`
1126          - :class:`ImageFFmpeg`
1127          - :class:`ImageBuff`
1128          - :class:`ImageMirror`
1129          - :class:`ImageMix`
1130          - :class:`ImageRender`
1131          - :class:`ImageViewport`
1132
1133    .. attribute:: keying
1134
1135       Specify if keying is enabled. False (default): the output frame is sent unmodified on
1136       the output interface (in that case no input video is required). True: the output frame
1137       is mixed with the input video, using the alpha channel to blend the two images and the
1138       combination is sent on the output interface.
1139
1140       :type: bool
1141
1142    .. attribute:: level
1143
1144       If keying is enabled, sets the keying level from 0 to 255. This value is a global alpha value
1145       that multiplies the alpha channel of the image source. Use 255 (the default) to keep the alpha
1146       channel unmodified, 0 to make the output frame totally transparent.
1147
1148       :type: int
1149
1150    .. attribute:: extend
1151
1152       Determines how the image source should be mapped if the size does not fit the video frame size.
1153       * False (the default): map the image pixel by pixel.
1154       If the image size is smaller than the frame size, extra space around the image is filled with
1155       0-alpha black. If it is larger, the image is cropped to fit the frame size.
1156       * True: the image is scaled by the nearest neighbor algorithm to fit the frame size.
1157       The scaling is fast but poor quality. For best results, always adjust the image source to
1158       match the size of the output video.
1159
1160       :type: bool
1161
1162    .. method:: close()
1163
1164       Close the DeckLink device and release all resources. After calling this method,
1165       the object cannot be reactivated, it must be destroyed and a new DeckLink object
1166       created from fresh to restart the output.
1167
1168    .. method:: refresh(refresh_source,ts)
1169
1170       This method must be called frequently to update the output frame in the DeckLink device.
1171
1172       :arg refresh_source: True if the source objects image buffer should be invalidated after being
1173          used to compute the output frame. This triggers the recomputing of the
1174          source image on next refresh, which is normally the desired effect.
1175          False if the image source buffer should stay valid and reused on next refresh.
1176          Note that the DeckLink device stores the output frame and replays until a
1177          new frame is sent from the host. Thus, it is not necessary to refresh the
1178          DeckLink object if it is known that the image source has not changed.
1179       :type refresh_source: bool
1180       :arg ts: The timestamp value passed to the image source object to compute the image.
1181          If unspecified, the BGE clock is used.
1182       :type ts: float
1183
1184
1185 **************
1186 Filter classes
1187 **************
1188
1189 .. class:: FilterBGR24
1190
1191    Source filter BGR24.
1192
1193 .. class:: FilterBlueScreen
1194
1195    Filter for Blue Screen.
1196    The RGB channels of the color are left unchanged, while the output alpha is obtained as follows:
1197
1198    - if the square of the euclidian distance between the RGB color
1199      and the filter's reference color is smaller than the filter's lower limit,
1200      the output alpha is set to 0;
1201    - if that square is bigger than the filter's upper limit, the output alpha is set to 255;
1202    - otherwise the output alpha is linarly extrapoled between 0 and 255 in the interval of the limits.
1203
1204    .. attribute:: color
1205
1206       Reference color.
1207
1208       :type: sequence of three ints
1209       :default: (0, 0, 255)
1210
1211    .. attribute:: limits
1212
1213       Reference color limits.
1214
1215       :type: sequence of two ints
1216       :default: (64, 64)
1217
1218    .. attribute:: previous
1219
1220       Previous pixel filter.
1221
1222       :type: one of...
1223
1224          * :class:`FilterBGR24`
1225          * :class:`FilterBlueScreen`
1226          * :class:`FilterColor`
1227          * :class:`FilterGray`
1228          * :class:`FilterLevel`
1229          * :class:`FilterNormal`
1230          * :class:`FilterRGB24`
1231          * :class:`FilterRGBA32`
1232
1233 .. class:: FilterColor
1234
1235    Filter for color calculations.
1236    The output color is obtained by multiplying the reduced 4x4 matrix with the input color
1237    and adding the remaining column to the result.
1238
1239    .. attribute:: matrix
1240
1241       Matrix [4][5] for color calculation.
1242
1243       :type: sequence of four sequences of five ints
1244       :default: ((256, 0, 0, 0, 0), (0, 256, 0, 0, 0), (0, 0, 256, 0, 0), (0, 0, 0, 256, 0))
1245
1246    .. attribute:: previous
1247
1248       Previous pixel filter.
1249
1250       :type: one of...
1251
1252          * :class:`FilterBGR24`
1253          * :class:`FilterBlueScreen`
1254          * :class:`FilterColor`
1255          * :class:`FilterGray`
1256          * :class:`FilterLevel`
1257          * :class:`FilterNormal`
1258          * :class:`FilterRGB24`
1259          * :class:`FilterRGBA32`
1260
1261 .. class:: FilterGray
1262
1263    Filter for gray scale effect.
1264    Proportions of R, G and B contributions in the output gray scale are 28:151:77.
1265
1266    .. attribute:: previous
1267
1268       Previous pixel filter.
1269
1270       :type: one of...
1271
1272          * :class:`FilterBGR24`
1273          * :class:`FilterBlueScreen`
1274          * :class:`FilterColor`
1275          * :class:`FilterGray`
1276          * :class:`FilterLevel`
1277          * :class:`FilterNormal`
1278          * :class:`FilterRGB24`
1279          * :class:`FilterRGBA32`
1280
1281 .. class:: FilterLevel
1282
1283    Filter for levels calculations. Each output color component is obtained as follows:
1284
1285    * if it is smaller than its corresponding min value, it is set to 0;
1286
1287    * if it is bigger than its corresponding max value, it is set to 255;
1288
1289    * Otherwise it is linearly extrapoled between 0 and 255 in the (min, max) interval.
1290
1291    .. attribute:: levels
1292
1293       Levels matrix [4] (min, max).
1294
1295       :type: sequence of four sequences of two ints
1296       :default: ((0, 255), (0, 255), (0, 255), (0, 255))
1297
1298    .. attribute:: previous
1299
1300       Previous pixel filter.
1301
1302       :type: one of...
1303
1304          * :class:`FilterBGR24`
1305          * :class:`FilterBlueScreen`
1306          * :class:`FilterColor`
1307          * :class:`FilterGray`
1308          * :class:`FilterLevel`
1309          * :class:`FilterNormal`
1310          * :class:`FilterRGB24`
1311          * :class:`FilterRGBA32`
1312
1313 .. class:: FilterNormal
1314
1315    Normal map filter.
1316
1317    .. attribute:: colorIdx
1318
1319       Index of color used to calculate normal (0 - red, 1 - green, 2 - blue, 3 - alpha).
1320
1321       :type: int in [0, 3]
1322       :default: 0
1323
1324    .. attribute:: depth
1325
1326       Depth of relief.
1327
1328       :type: float
1329       :default: 4.0
1330
1331    .. attribute:: previous
1332
1333       Previous pixel filter.
1334
1335       :type: one of...
1336
1337          * :class:`FilterBGR24`
1338          * :class:`FilterBlueScreen`
1339          * :class:`FilterColor`
1340          * :class:`FilterGray`
1341          * :class:`FilterLevel`
1342          * :class:`FilterNormal`
1343          * :class:`FilterRGB24`
1344          * :class:`FilterRGBA32`
1345
1346 .. class:: FilterRGB24
1347
1348    Returns a new input filter object to be used with :class:`ImageBuff` object when the image passed
1349    to the :meth:`ImageBuff.load` function has the 3-bytes pixel format BGR.
1350
1351 .. class:: FilterRGBA32
1352
1353    Source filter RGBA32.
1354
1355
1356 *********
1357 Functions
1358 *********
1359
1360 .. function:: getLastError()
1361
1362    Last error that occurred in a bge.texture function.
1363
1364    :return: The description of the last error occurred in a bge.texture function.
1365    :rtype: str
1366
1367 .. function:: imageToArray(image, mode)
1368
1369    Returns a :class:`~bgl.Buffer` corresponding to the current image stored in a texture source object.
1370
1371    :arg image: Image source object of type ...
1372
1373       * :class:`VideoFFmpeg`
1374       * :class:`ImageFFmpeg`
1375       * :class:`ImageBuff`
1376       * :class:`ImageMirror`
1377       * :class:`ImageMix`
1378       * :class:`ImageRender`
1379       * :class:`ImageViewport`
1380
1381    :arg mode: Optional argument representing the pixel format.
1382
1383       - You can use the characters R, G, B for the 3 color channels, A for the alpha channel,
1384         0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
1385
1386         Examples:
1387
1388         - "BGR" will return 3 bytes per pixel with the
1389           Blue, Green and Red channels in that order.
1390         - "RGB1" will return 4 bytes per pixel with the 
1391           Red, Green, Blue channels in that order and the alpha channel forced to 255.
1392
1393       - A special mode "F" allows to return the image as an array of float.
1394         This mode should only be used to retrieve the depth buffer of the
1395         class:`ImageViewport` and :class:`ImageRender` objects.
1396         The default mode is "RGBA".
1397
1398    :type mode: str
1399
1400    :return: An object representing the image as one dimensional array of bytes of size (pixel_size*width*height),
1401       line by line starting from the bottom of the image. The pixel size and format is determined by the mode
1402       parameter. For mode 'F', the array is a one dimensional array of float of size (width*height).
1403    :rtype: :class:`~bgl.Buffer`
1404
1405 .. function:: materialID(object, name)
1406
1407    Returns a numeric value that can be used in :class:`Texture` to create a dynamic texture.
1408
1409    The value corresponds to an internal material number that uses the texture identified
1410    by name. name is a string representing a texture name with ``IM`` prefix if you want to
1411    identify the texture directly. This method works for basic tex face and for material,
1412    provided the material has a texture channel using that particular texture in first
1413    position of the texture stack. name can also have ``MA`` prefix if you want to identify
1414    the texture by material. In that case the material must have a texture channel in first
1415    position.
1416
1417    If the object has no material that matches name, it generates a runtime error.
1418    Use try/except to catch the exception.
1419
1420    Ex: ``bge.texture.materialID(obj, 'IMvideo.png')``
1421
1422    :arg object: The game object that uses the texture you want to make dynamic.
1423    :type object: :class:`~bge.types.KX_GameObject`
1424    :arg name: Name of the texture/material you want to make dynamic.
1425    :type name: str
1426
1427    :return: The internal material number.
1428    :rtype: int
1429
1430 .. function:: setLogFile(filename)
1431
1432    Sets the name of a text file in which runtime error messages will be written, in addition to the printing
1433    of the messages on the Python console. Only the runtime errors specific to the VideoTexture module
1434    are written in that file, ordinary runtime time errors are not written.
1435
1436    :arg filename: Name of the error log file.
1437    :type filename: str
1438
1439    :return: -1 if the parameter name is invalid (not of type string), else 0.
1440    :rtype: int
1441
1442
1443 *********
1444 Constants
1445 *********
1446
1447 FFmpeg Video and Image Status
1448 +++++++++++++++++++++++++++++
1449
1450
1451 .. data:: SOURCE_ERROR
1452
1453 .. data:: SOURCE_EMPTY
1454
1455 .. data:: SOURCE_READY
1456
1457 .. data:: SOURCE_PLAYING
1458
1459 .. data:: SOURCE_STOPPED
1460
1461
1462 Image Blending Modes
1463 ++++++++++++++++++++
1464
1465 See Wikipedia's `Blend Modes <https://en.wikipedia.org/wiki/Blend_modes>`_ for reference.
1466
1467 .. data:: IMB_BLEND_MIX
1468
1469 .. data:: IMB_BLEND_ADD
1470
1471 .. data:: IMB_BLEND_SUB
1472
1473 .. data:: IMB_BLEND_MUL
1474
1475 .. data:: IMB_BLEND_LIGHTEN
1476
1477 .. data:: IMB_BLEND_DARKEN
1478
1479 .. data:: IMB_BLEND_ERASE_ALPHA
1480
1481 .. data:: IMB_BLEND_ADD_ALPHA
1482
1483 .. data:: IMB_BLEND_OVERLAY
1484
1485 .. data:: IMB_BLEND_HARDLIGHT
1486
1487 .. data:: IMB_BLEND_COLORBURN
1488
1489 .. data:: IMB_BLEND_LINEARBURN
1490
1491 .. data:: IMB_BLEND_COLORDODGE
1492
1493 .. data:: IMB_BLEND_SCREEN
1494
1495 .. data:: IMB_BLEND_SOFTLIGHT
1496
1497 .. data:: IMB_BLEND_PINLIGHT
1498
1499 .. data:: IMB_BLEND_VIVIDLIGHT
1500
1501 .. data:: IMB_BLEND_LINEARLIGHT
1502
1503 .. data:: IMB_BLEND_DIFFERENCE
1504
1505 .. data:: IMB_BLEND_EXCLUSION
1506
1507 .. data:: IMB_BLEND_HUE
1508
1509 .. data:: IMB_BLEND_SATURATION
1510
1511 .. data:: IMB_BLEND_LUMINOSITY
1512
1513 .. data:: IMB_BLEND_COLOR
1514
1515 .. data:: IMB_BLEND_COPY
1516
1517 .. data:: IMB_BLEND_COPY_RGB
1518
1519 .. data:: IMB_BLEND_COPY_ALPHA
1520