BGE: bge.texture API documentation enhancement

This patch attempts to improve and review the documentation of bge.texture, as requested in the [[ http://wiki.blender.org/index.php/Dev:2.5/Source/Development/Todo/GameEngine#Video_Texture | TODO list ]].

More specifically, it

  - fixes the rst syntax, including titles of the examples bge.texture.py and bge.texture.1.py;

  - adds, standardizes and reviews description of the API elements, particularly signatures, types, etc.

  - adds SOURCE_* constants to the doc

  - splits the doc into thematical parts (Video, Image, Texture, and Filter Classes, Functions, Constants).

Notes:

  - The parameter "mode" of ImageBuff.plot has to be described better. Actually, the whole set of IMB_BLEND_* constants (from IMB_imbuf.h) should be exposed to Python. I'll do that in a future diff, and complete the doc at the same moment (adding those IMB_BLEND_* constants to the Constants part of this doc).

  - The option of using webcams in VideoFFmpeg is still particularly not well documented. I am planning to make a proposal about fixing T18634 (and its corresponding TODO in the list) by integrating OpenCV in the BGE (and Blender?). The idea would then probably be to add a new class, f.ex. ImageWebcam, making this functionnality more specialized. So for now I don't think it is worth to document that part much.

This patch fixes T44284 too.

Reviewers: moguri, kupoman, campbellbarton, panzergame, lordloki

Reviewed By: panzergame, lordloki

Subscribers: hg1

Projects: #game_engine, #game_python, #documentation

Maniphest Tasks: T44284

Differential Revision: https://developer.blender.org/D1352

3 files changed, 872 insertions, 216 deletions

diff --git a/doc/python_api/examples/bge.texture.1.py b/doc/python_api/examples/bge.texture.1.py
index fba369739f7..bee1f251afa 100644
--- a/doc/python_api/examples/bge.texture.1.py
+++ b/doc/python_api/examples/bge.texture.1.py
@@ -2,8 +2,8 @@
 Texture Replacement
 +++++++++++++++++++
 Example of how to replace a texture in game with an external image.
-createTexture() and removeTexture() are to be called from a module Python
-Controller.
+``createTexture()`` and ``removeTexture()`` are to be called from a
+module Python Controller.
 """
 from bge import logic
 from bge import texture
diff --git a/doc/python_api/examples/bge.texture.py b/doc/python_api/examples/bge.texture.py
index 1ba0b99fc27..ac1f5a21447 100644
--- a/doc/python_api/examples/bge.texture.py
+++ b/doc/python_api/examples/bge.texture.py
@@ -1,7 +1,8 @@
 """
 Basic Video Playback
 ++++++++++++++++++++
-Example of how to replace a texture in game with a video. It needs to run everyframe
+Example of how to replace a texture in game with a video. It needs to run
+everyframe.
 """
 import bge
 from bge import texture
diff --git a/doc/python_api/rst/bge.texture.rst b/doc/python_api/rst/bge.texture.rst
index dde26616e78..90d56c9aaf7 100644
--- a/doc/python_api/rst/bge.texture.rst
+++ b/doc/python_api/rst/bge.texture.rst
@@ -2,9 +2,9 @@
 Video Texture (bge.texture)
 ===========================
 
-*****
-Intro
-*****
+************
+Introduction
+************
 
 The bge.texture module allows you to manipulate textures during the game.
 
@@ -14,7 +14,7 @@ The video and image files can be loaded from the internet using an URL instead o
 
 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.
 
-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::
+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:
 
 * AVI
 * Ogg
@@ -26,7 +26,7 @@ bge.texture uses FFmpeg to load images and videos. All the formats and codecs th
 * JPG
 
 The principle is simple: first you identify a texture on an existing object using
-the :materialID: function, then you create a new texture with dynamic content
+the :class:`~bge.texture.materialID` function, then you create a new texture with dynamic content
 and swap the two textures in the GPU.
 
 The GE is not aware of the substitution and continues to display the object as always,
@@ -36,542 +36,1052 @@ When the texture object is deleted, the new texture is deleted and the old textu
 
 .. module:: bge.texture
 
+.. include:: ../examples/bge.texture.py
+   :start-line: 1
+   :end-line: 5
+   
 .. literalinclude:: ../examples/bge.texture.py
-   :language: rest
-   :lines: 2-4
-
-.. literalinclude:: ../examples/bge.texture.py
-   :lines: 6-
-
-.. literalinclude:: ../examples/bge.texture.1.py
-   :language: rest
-   :lines: 2-6
+   :lines: 7-
 
+.. include:: ../examples/bge.texture.1.py
+   :start-line: 1
+   :end-line: 6
+   
 .. literalinclude:: ../examples/bge.texture.1.py
    :lines: 8-
-
-.. class:: VideoFFmpeg(file [, capture=-1, rate=25.0, width=0, height=0])
-
-   FFmpeg video source
+   
+   
+*************
+Video classes
+*************
+
+.. class:: VideoFFmpeg(file, capture=-1, rate=25.0, width=0, height=0)
+
+   FFmpeg video source.
+      
+   :arg file: Path to the video to load; if capture >= 0 on Windows, this parameter will not be used.
+   :type file: str
+   :arg capture: Capture device number; if >= 0, the corresponding webcam will be used. (optional)
+   :type capture: int
+   :arg rate: Capture rate. (optional, used only if capture >= 0)
+   :type rate: float
+   :arg width: Capture width. (optional, used only if capture >= 0)
+   :type width: int
+   :arg height: Capture height. (optional, used only if capture >= 0)
+   :type height: int
 
    .. attribute:: status
 
-      video status
+      Video status. (readonly)
+      
+      :type: int
+      :value: one of...
+      
+         * :data:`SOURCE_ERROR`
+         * :data:`SOURCE_EMPTY`
+         * :data:`SOURCE_READY`
+         * :data:`SOURCE_PLAYING`
+         * :data:`SOURCE_STOPPED`
+      
 
    .. attribute:: range
 
-      replay range
+      Replay range.
+      
+      :type: sequence of two floats
 
    .. attribute:: repeat
 
-      repeat count, -1 for infinite repeat
+      Repeat count, -1 for infinite repeat.
 
       :type: int
 
    .. attribute:: framerate
 
-      frame rate
+      Frame rate.
 
       :type: float
 
    .. attribute:: valid
 
-      Tells if an image is available
+      Tells if an image is available. (readonly)
 
       :type: bool
 
    .. attribute:: image
 
-      image data
+      Image data. (readonly)
+      
+      :type: :class:`~bgl.Buffer` or None
 
    .. attribute:: size
 
-      image size
+      Image size. (readonly)
+      
+      :type: tuple of two ints
 
    .. attribute:: scale
 
-      fast scale of image (near neighbour)
+      Fast scale of image (near neighbour).
+      
+      :type: bool
 
    .. attribute:: flip
 
-      flip image vertically
+      Flip image vertically.
+      
+      :type: bool
 
    .. attribute:: filter
 
-      pixel filter
+      Pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
    .. attribute:: preseek
 
-      number of frames of preseek
+      Number of frames of preseek.
 
       :type: int
 
    .. attribute:: deinterlace
 
-      deinterlace image
+      Deinterlace image.
 
       :type: bool
 
    .. method:: play()
 
-      Play (restart) video
+      Play (restart) video.
+      
+      :return: Whether the video was ready or stopped.
+      :rtype: bool
 
    .. method:: pause()
 
-      pause video
+      Pause video.
+      
+      :return: Whether the video was playing.
+      :rtype: bool
 
    .. method:: stop()
 
-      stop video (play will replay it from start)
+      Stop video (play will replay it from start).
+      
+      :return: Whether the video was playing.
+      :rtype: bool
 
    .. method:: refresh()
 
-      Refresh video - get its status
+      Refresh video - get its status.
+      
+      :return: The video's status, one of...
+      
+         * :data:`SOURCE_ERROR`
+         * :data:`SOURCE_EMPTY`
+         * :data:`SOURCE_READY`
+         * :data:`SOURCE_PLAYING`
+         * :data:`SOURCE_STOPPED`
+      
+      :rtype: int
+
+*************
+Image classes
+*************
 
 .. class:: ImageFFmpeg(file)
 
-   FFmpeg image source
+   FFmpeg image source.
+      
+   :arg file: Path to the image to load.
+   :type file: str
 
    .. attribute:: status
 
-      video status
+      Image status. (readonly)
+      
+      :type: int
+      :value: one of...
+      
+         * :data:`SOURCE_ERROR`
+         * :data:`SOURCE_EMPTY`
+         * :data:`SOURCE_READY`
+         * :data:`SOURCE_PLAYING`
+         * :data:`SOURCE_STOPPED`
 
    .. attribute:: valid
 
-      Tells if an image is available
+      Tells if an image is available. (readonly)
 
       :type: bool
 
    .. attribute:: image
 
-      image data
+      Image data. (readonly)
+      
+      :type: :class:`~bgl.Buffer` or None
 
    .. attribute:: size
 
-      image size
+      Image size. (readonly)
+      
+      :type: tuple of two ints
 
    .. attribute:: scale
 
-      fast scale of image (near neighbour)
+      Fast scale of image (near neighbour).
+      
+      :type: bool
 
    .. attribute:: flip
 
-      flip image vertically
+      Flip image vertically.
+      
+      :type: bool
 
    .. attribute:: filter
 
-      pixel filter
+      Pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
    .. method:: refresh()
 
-      Refresh image, i.e. load it
-
-   .. method:: reload([newname])
-
-      Reload image, i.e. reopen it
-
-.. class:: ImageBuff()
-
-   Image source from image buffer
+      Refresh image, i.e. load it.
+      
+      :return: the video's status, one of...
+      
+         * :data:`SOURCE_ERROR`
+         * :data:`SOURCE_EMPTY`
+         * :data:`SOURCE_READY`
+         * :data:`SOURCE_PLAYING`
+         * :data:`SOURCE_STOPPED`
+      
+      :rtype: int
+
+   .. method:: reload(newname=None)
+
+      Reload image, i.e. reopen it.
+      
+      :arg newname: Path to a new image. (optional)
+      :type newname: str
+
+.. class:: ImageBuff(width, height, color=0, scale=False)
+
+   Image source from image buffer.
+   
+   :arg width: Width of the image.
+   :type width: int
+   :arg height: Height of the image.
+   :type height: int
+   :arg color: Value to initialize RGB channels with. The initialized buffer will have
+               all pixels set to (color, color, color, 255). (optional)
+   :type color: int in [0, 255]
+   :arg scale: Image uses scaling. (optional)
+   :type scale: bool
 
    .. attribute:: filter
 
-      pixel filter
+      Pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
    .. attribute:: flip
 
-      flip image vertically
+      Flip image vertically.
+      
+      :type: bool
 
    .. attribute:: image
 
-      image data
+      Image data. (readonly)
+      
+      :type: :class:`~bgl.Buffer` or None
 
    .. method:: load(imageBuffer, width, height)
 
-      Load image from buffer
-
-   .. method:: plot(imageBuffer, width, height, positionX, positionY)
-
-      update image buffer
+      Load image from buffer.
+      
+      :arg imageBuffer: Buffer to load the image from.
+      :type imageBuffer: :class:`~bgl.Buffer` or Python object implementing the buffer protocol (f.ex. bytes)
+      :arg width: Width of the image to load.
+      :type width: int
+      :arg height: Height of the image to load.
+      :type height: int
+
+   .. method:: plot(imageBuffer, width, height, positionX, positionY, mode=IMB_BLEND_COPY)
+
+      Update image buffer.
+      
+      :arg imageBuffer: Buffer to load the new data from.
+      :type imageBuffer: :class:`~bgl.Buffer`, :class:`ImageBuff` or Python object implementing the buffer protocol (f.ex. bytes)
+      :arg width: Width of the data to load.
+      :type width: int
+      :arg height: Height of the data to load.
+      :type height: int
+      :arg positionX: Left boundary of the region to be drawn on.
+      :type positionX: int
+      :arg positionY: Upper boundary of the region to be drawn on.
+      :type positionY: int
+      :arg mode: Drawing mode, one of... (optional)
+      
+         * :data:`IMB_BLEND_MIX`
+         * :data:`IMB_BLEND_ADD`
+         * :data:`IMB_BLEND_SUB`
+         * :data:`IMB_BLEND_MUL`
+         * :data:`IMB_BLEND_LIGHTEN`
+         * :data:`IMB_BLEND_DARKEN`
+         * :data:`IMB_BLEND_ERASE_ALPHA`
+         * :data:`IMB_BLEND_ADD_ALPHA`
+         * :data:`IMB_BLEND_OVERLAY`
+         * :data:`IMB_BLEND_HARDLIGHT`
+         * :data:`IMB_BLEND_COLORBURN`
+         * :data:`IMB_BLEND_LINEARBURN`
+         * :data:`IMB_BLEND_COLORDODGE`
+         * :data:`IMB_BLEND_SCREEN`
+         * :data:`IMB_BLEND_SOFTLIGHT`
+         * :data:`IMB_BLEND_PINLIGHT`
+         * :data:`IMB_BLEND_VIVIDLIGHT`
+         * :data:`IMB_BLEND_LINEARLIGHT`
+         * :data:`IMB_BLEND_DIFFERENCE`
+         * :data:`IMB_BLEND_EXCLUSION`
+         * :data:`IMB_BLEND_HUE`
+         * :data:`IMB_BLEND_SATURATION`
+         * :data:`IMB_BLEND_LUMINOSITY`
+         * :data:`IMB_BLEND_COLOR`
+         * :data:`IMB_BLEND_COPY`
+         * :data:`IMB_BLEND_COPY_RGB`
+         * :data:`IMB_BLEND_COPY_ALPHA`
+      
+      :type mode: int
+      
 
    .. attribute:: scale
 
-      fast scale of image (near neighbour)
+      Fast scale of image (near neighbour).
+      
+      :type: bool
 
    .. attribute:: size
 
-      image size
+      Image size. (readonly)
+      
+      :type: tuple of two ints
 
    .. attribute:: valid
 
-      bool to tell if an image is available
+      Tells if an image is available. (readonly)
+
+      :type: bool
 
-.. class:: ImageMirror(scene)
+.. class:: ImageMirror(scene, observer, mirror, material=0)
 
-   Image source from mirror
+   Image source from mirror.
+   
+   :arg scene: Scene in which the image has to be taken.
+   :type scene: :class:`~bge.types.KX_Scene`
+   :arg observer: Reference object for the mirror (the object from which the mirror has to be looked at, for example a camera).
+   :type observer: :class:`~bge.types.KX_GameObject`
+   :arg mirror: Object holding the mirror.
+   :type mirror: :class:`~bge.types.KX_GameObject`
+   :arg material: ID of the mirror's material to be used for mirroring. (optional)
+   :type material: int
 
    .. attribute:: alpha
 
-      use alpha in texture
+      Use alpha in texture.
+      
+      :type: bool
 
    .. attribute:: background
 
-      background color
-
+      Background color.
+      
       :type: int or float list [r, g, b, a] in [0.0, 255.0]
 
    .. attribute:: capsize
 
-      size of render area
+      Size of render area.
+      
+      :type: sequence of two ints
 
    .. attribute:: clip
 
-      clipping distance
+      Clipping distance.
+      
+      :type: float in [0.01, 5000.0]
 
    .. attribute:: filter
 
-      pixel filter
+      Pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
    .. attribute:: flip
 
-      flip image vertically
+      Flip image vertically.
+      
+      :type: bool
 
    .. attribute:: image
 
-      image data
+      Image data. (readonly)
+      
+      :type: :class:`~bgl.Buffer` or None
 
-   .. method:: refresh(imageMirror)
+   .. method:: refresh()
 
-      Refresh image - invalidate its current content
+      Refresh image - invalidate its current content.
 
    .. attribute:: scale
 
-      fast scale of image (near neighbour)
+      Fast scale of image (near neighbour).
+      
+      :type: bool
 
    .. attribute:: size
 
-      image size
+      Image size (readonly).
+      
+      :type: tuple of two ints
 
    .. attribute:: valid
 
-      bool to tell if an image is available
+      Tells if an image is available. (readonly)
+
+      :type: bool
 
    .. attribute:: whole
 
-      use whole viewport to render
+      Use whole viewport to render.
+      
+      :type: bool
 
-.. class:: ImageMix()
+.. class:: ImageMix
 
-   Image mixer
+   Image mixer.
 
    .. attribute:: filter
 
-      pixel filter
+      Pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
    .. attribute:: flip
 
-      flip image vertically
-
-   .. method:: getSource(imageMix)
-
-      get image source
-
-   .. method:: getWeight(imageMix)
-
-      get image source weight
+      Flip image vertically.
+      
+      :type: bool
 
+   .. method:: getSource(id)
+
+      Get image source.
+      
+      :arg id: Identifier of the source to get.
+      :type id: str
+      
+      :return: Image source.
+      :rtype: one of...
+      
+         * :class:`VideoFFmpeg`
+         * :class:`ImageFFmpeg`
+         * :class:`ImageBuff`
+         * :class:`ImageMirror`
+         * :class:`ImageMix`
+         * :class:`ImageRender`
+         * :class:`ImageViewport`
+
+   .. method:: getWeight(id)
+
+      Get image source weight.
+      
+      :arg id: Identifier of the source.
+      :type id: str
+      
+      :return: Weight of the source.
+      :rtype: int
 
    .. attribute:: image
 
-      image data
+      Image data. (readonly)
+      
+      :type: :class:`~bgl.Buffer` or None
 
-   .. method:: refresh(imageMix)
+   .. method:: refresh()
 
-      Refresh image - invalidate its current content
+      Refresh image - invalidate its current content.
 
    .. attribute:: scale
 
-      fast scale of image (near neighbour)
-
-   .. method:: setSource(imageMix)
-
-      set image source
-
-   .. method:: setWeight(imageMix)
+      Fast scale of image (near neighbour).
+      
+      :type: bool
+      
+   .. attribute:: size
 
-      set image source weight
+      Image size. (readonly)
+      
+      :type: tuple of two ints
+
+   .. method:: setSource(id, image)
+
+      Set image source - all sources must have the same size.
+      
+      :arg id: Identifier of the source to set.
+      :type id: str
+      :arg image: Image source of type...
+      
+         * :class:`VideoFFmpeg`
+         * :class:`ImageFFmpeg`
+         * :class:`ImageBuff`
+         * :class:`ImageMirror`
+         * :class:`ImageMix`
+         * :class:`ImageRender`
+         * :class:`ImageViewport`
+
+   .. method:: setWeight(id, weight)
+
+      Set image source weight - the sum of the weights should be 256 to get full color intensity in the output.
+      
+      :arg id: Identifier of the source.
+      :type id: str
+      :arg weight: Weight of the source.
+      :type weight: int
 
    .. attribute:: valid
 
-      bool to tell if an image is available
+      Tells if an image is available. (readonly)
+
+      :type: bool
 
 .. class:: ImageRender(scene, camera)
 
-   Image source from render
+   Image source from render.
+   
+   :arg scene: Scene in which the image has to be taken.
+   :type scene: :class:`~bge.types.KX_Scene`
+   :arg camera: Camera from which the image has to be taken.
+   :type camera: :class:`~bge.types.KX_Camera`
 
    .. attribute:: alpha
 
-      use alpha in texture
+      Use alpha in texture.
+      
+      :type: bool
 
    .. attribute:: background
 
-      background color
-
+      Background color.
+      
       :type: int or float list [r, g, b, a] in [0.0, 255.0]
 
    .. attribute:: capsize
 
-      size of render area
+      Size of render area.
+      
+      :type: sequence of two ints
 
    .. attribute:: filter
 
-      pixel filter
+      Pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
    .. attribute:: flip
 
-      flip image vertically
+      Flip image vertically.
+      
+      :type: bool
 
    .. attribute:: image
 
-      image data
+      Image data. (readonly)
+      
+      :type: :class:`~bgl.Buffer` or None
 
-   .. method:: refresh(imageRender)
+   .. method:: refresh()
 
-      Refresh image - invalidate its current content
+      Refresh image - invalidate its current content.
 
    .. attribute:: scale
 
-      fast scale of image (near neighbour)
+      Fast scale of image (near neighbour).
+      
+      :type: bool
 
    .. attribute:: size
 
-      image size
+      Image size. (readonly)
+      
+      :type: tuple of two ints
 
    .. attribute:: valid
 
-      bool to tell if an image is available
+      Tells if an image is available. (readonly)
+
+      :type: bool
 
    .. attribute:: whole
 
-      use whole viewport to render
+      Use whole viewport to render.
+      
+      :type: bool
 
    .. attribute:: depth
 
-      use depth component of render as array of float -  not suitable for texture source,
-      should only be used with bge.texture.imageToArray(mode='F')
+      Use depth component of render as array of float - not suitable for texture source,
+      should only be used with bge.texture.imageToArray(mode='F').
+      
+      :type: bool
 
    .. attribute:: zbuff
 
-      use depth component of render as grey scale color -  suitable for texture source
+      Use depth component of render as grey scale color -  suitable for texture source.
+      
+      :type: bool
 
-.. class:: ImageViewport()
+.. class:: ImageViewport
 
-   Image source from viewport
+   Image source from viewport.
 
    .. attribute:: alpha
 
-      use alpha in texture
+      Use alpha in texture.
+      
+      :type: bool
 
    .. attribute:: capsize
 
-      size of viewport area being captured
+      Size of viewport area being captured.
+      
+      :type: sequence of two ints
 
    .. attribute:: filter
 
-      pixel filter
+      Pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
    .. attribute:: flip
 
-      flip image vertically
+      Flip image vertically.
+      
+      :type: bool
 
    .. attribute:: image
 
-      image data
+      Image data. (readonly)
+      
+      :type: :class:`~bgl.Buffer` or None
 
    .. attribute:: position
 
-      upper left corner of captured area
+      Upper left corner of the captured area.
+      
+      :type: sequence of two ints
 
-   .. method:: refresh(imageViewport)
+   .. method:: refresh()
 
-      Refresh image - invalidate its current content
+      Refresh image - invalidate its current content.
 
    .. attribute:: scale
 
-      fast scale of image (near neighbour)
+      Fast scale of image (near neighbour).
+      
+      :type: bool
 
    .. attribute:: size
 
-      image size
+      Image size. (readonly)
+      
+      :type: tuple of two ints
 
    .. attribute:: valid
 
-      bool to tell if an image is available
+      Tells if an image is available. (readonly)
+
+      :type: bool
 
    .. attribute:: whole
 
-      use whole viewport to capture
+      Use whole viewport to capture.
+      
+      :type: bool
 
    .. attribute:: depth
 
-      use depth component of viewport as array of float -  not suitable for texture source,
-      should only be used with bge.texture.imageToArray(mode='F')
+      Use depth component of viewport as array of float - not suitable for texture source,
+      should only be used with bge.texture.imageToArray(mode='F').
+      
+      :type: bool
 
    .. attribute:: zbuff
 
-      use depth component of viewport as grey scale color -  suitable for texture source
+      Use depth component of viewport as grey scale color -  suitable for texture source.
+      
+      :type: bool
+
+   
+***************
+Texture classes
+***************
 
-.. class:: Texture(gameObj)
+.. class:: Texture(gameObj, materialID=0, textureID=0, textureObj=None)
 
-   Texture objects
+   Texture object.
+   
+   :arg gameObj: Game object to be created a video texture on.
+   :type gameObj: :class:`~bge.types.KX_GameObject`
+   :arg materialID: Material ID. (optional)
+   :type materialID: int
+   :arg textureID: Texture ID. (optional)
+   :type textureID: int
+   :arg textureObj: Texture object with shared bindId. (optional)
+   :type textureObj: :class:`Texture`
 
    .. attribute:: bindId
 
-      OpenGL Bind Name
+      OpenGL Bind Name. (readonly)
+      
+      :type: int
 
-   .. method:: close(texture)
+   .. method:: close()
 
-      Close dynamic texture and restore original
+      Close dynamic texture and restore original.
 
    .. attribute:: mipmap
 
-      mipmap texture
+      Mipmap texture.
+      
+      :type: bool
 
-   .. method:: refresh(texture)
+   .. method:: refresh(refresh_source=True, ts=-1.0)
 
-      Refresh texture from source
+      Refresh texture from source.
+      
+      :arg refresh_source: Whether to also refresh the image source of the texture.
+      :type refresh_source: bool
+      :arg ts: If the texture controls a VideoFFmpeg object:
+               timestamp (in seconds from the start of the movie) of the frame to be loaded; this can be
+               used for video-sound synchonization by passing :attr:`~bge.types.KX_SoundActuator.time` to it. (optional)
+      :type ts: float
 
    .. attribute:: source
 
-      source of texture
+      Source of texture.
+      
+      :type: one of...
+      
+         * :class:`VideoFFmpeg`
+         * :class:`ImageFFmpeg`
+         * :class:`ImageBuff`
+         * :class:`ImageMirror`
+         * :class:`ImageMix`
+         * :class:`ImageRender`
+         * :class:`ImageViewport`
 
-.. class:: FilterBGR24()
+   
+**************
+Filter classes
+**************
 
-   Source filter BGR24 objects
 
-.. class:: FilterBlueScreen()
+.. class:: FilterBGR24
 
-   Filter for Blue Screen objects
+   Source filter BGR24.
+
+.. class:: FilterBlueScreen
+
+   Filter for Blue Screen. The RGB channels of the color are left unchanged, while the output alpha is obtained as follows:
+   
+   * 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,
+     the output alpha is set to 0;
+   
+   * if that square is bigger than the filter's upper limit, the output alpha is set to 255;
+   
+   * otherwise the output alpha is linarly extrapoled between 0 and 255 in the interval of the limits.
 
    .. attribute:: color
 
-      blue screen color
+      Reference color.
+      
+      :type: sequence of three ints
+      :default: (0, 0, 255)
 
    .. attribute:: limits
 
-      blue screen color limits
+      Reference color limits.
+      
+      :type: sequence of two ints
+      :default: (64, 64)
 
    .. attribute:: previous
 
-      previous pixel filter
+      Previous pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
-.. class:: FilterColor()
+.. class:: FilterColor
 
-   Filter for color calculations
+   Filter for color calculations. The output color is obtained by multiplying the reduced 4x4 matrix with the input color
+   and adding the remaining column to the result.
 
    .. attribute:: matrix
 
-      matrix [4][5] for color calculation
+      Matrix [4][5] for color calculation.
+      
+      :type: sequence of four sequences of five ints
+      :default: ((256, 0, 0, 0, 0), (0, 256, 0, 0, 0), (0, 0, 256, 0, 0), (0, 0, 0, 256, 0))
 
    .. attribute:: previous
 
-      previous pixel filter
+      Previous pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
-.. class:: FilterGray()
+.. class:: FilterGray
 
-   Filter for gray scale effect
+   Filter for gray scale effect. Proportions of R, G and B contributions in the output gray scale are 28:151:77.
 
    .. attribute:: previous
 
-      previous pixel filter
-
-.. class:: FilterLevel()
-
-   Filter for levels calculations
+      Previous pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
+
+.. class:: FilterLevel
+
+   Filter for levels calculations. Each output color component is obtained as follows:
+   
+   * if it is smaller than its corresponding min value, it is set to 0;
+   
+   * if it is bigger than its corresponding max value, it is set to 255;
+   
+   * Otherwise it is linearly extrapoled between 0 and 255 in the (min, max) interval.
 
    .. attribute:: levels
 
-      levels matrix [4] (min, max)
+      Levels matrix [4] (min, max).
+      
+      :type: sequence of four sequences of two ints
+      :default: ((0, 255), (0, 255), (0, 255), (0, 255))
 
    .. attribute:: previous
 
-      previous pixel filter
+      Previous pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
 
-.. class:: FilterNormal()
+.. class:: FilterNormal
 
-   Filter for Blue Screen objects
+   Normal map filter.
 
    .. attribute:: colorIdx
 
-      index of color used to calculate normal (0 - red, 1 - green, 2 - blue)
+      Index of color used to calculate normal (0 - red, 1 - green, 2 - blue, 3 - alpha).
+      
+      :type: int in [0, 3]
+      :default: 0
 
    .. attribute:: depth
 
-      depth of relief
+      Depth of relief.
+      
+      :type: float
+      :default: 4.0
 
    .. attribute:: previous
 
-      previous pixel filter
-
-.. class:: FilterRGB24()
+      Previous pixel filter.
+      
+      :type: one of...
+      
+         * :class:`FilterBGR24`
+         * :class:`FilterBlueScreen`
+         * :class:`FilterColor`
+         * :class:`FilterGray`
+         * :class:`FilterLevel`
+         * :class:`FilterNormal`
+         * :class:`FilterRGB24`
+         * :class:`FilterRGBA32`
+
+.. class:: FilterRGB24
 
    Returns a new input filter object to be used with :class:`ImageBuff` object when the image passed
-   to the ImageBuff.load() function has the 3-bytes pixel format BGR.
-
-.. class:: FilterRGBA32()
-
-   Source filter RGBA32 objects
-
-.. function:: getLastError()
+   to the :meth:`ImageBuff.load` function has the 3-bytes pixel format BGR.
 
-   Last error that occurred in a bge.texture function.
+.. class:: FilterRGBA32
 
-   :return: the description of the last error occurred in a bge.texture function.
-   :rtype: string
+   Source filter RGBA32.
 
-.. function:: imageToArray(image,mode)
 
-   Returns a :class:`~bgl.buffer` corresponding to the current image stored in a texture source object.
+*********
+Functions
+*********
 
-   :arg image: Image source object.
-   :type image: object of type :class:`VideoFFmpeg`, :class:`ImageFFmpeg`, :class:`ImageBuff`, :class:`ImageMix`, :class:`ImageRender`, :class:`ImageMirror` or :class:`ImageViewport`
-   :arg mode: optional argument representing the pixel format.
-      You can use the characters R, G, B for the 3 color channels, A for the alpha channel,
-      0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
-      Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order.
-      "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
-      A special mode "F" allows to return the image as an array of float. This mode should only be used to retrieve
-      the depth buffer of the ImageViewport and ImageRender object.
-      The default mode is "RGBA".
-          
+.. function:: getLastError()
 
-   :type mode: string
-   :rtype: :class:`~bgl.buffer`
-   :return: A object representing the image as one dimensional array of bytes of size (pixel_size*width*height),
-      line by line starting from the bottom of the image. The pixel size and format is determined by the mode
-      parameter. For mode 'F', the array is a one dimensional array of float of size (width*height).
+   Last error that occurred in a bge.texture function.
 
-.. function:: materialID(object,name)
+   :return: The description of the last error occurred in a bge.texture function.
+   :rtype: str
+
+.. function:: imageToArray(image, mode)
+
+   Returns a :class:`~bgl.Buffer` corresponding to the current image stored in a texture source object.
+
+   :arg image: Image source object of type ...
+
+      * :class:`VideoFFmpeg`
+      * :class:`ImageFFmpeg`
+      * :class:`ImageBuff`
+      * :class:`ImageMirror`
+      * :class:`ImageMix`
+      * :class:`ImageRender`
+      * :class:`ImageViewport`
+   
+   :arg mode: Optional argument representing the pixel format.
+              
+      * You can use the characters R, G, B for the 3 color channels, A for the alpha channel,
+        0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
+        
+        Examples:
+            * "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order.
+            * "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
+      
+      * A special mode "F" allows to return the image as an array of float. This mode should only be used to retrieve
+        the depth buffer of the class:`ImageViewport` and :class:`ImageRender` objects.
+        The default mode is "RGBA".
+   
+   :type mode: str
+   
+   :return: An object representing the image as one dimensional array of bytes of size (pixel_size*width*height),
+            line by line starting from the bottom of the image. The pixel size and format is determined by the mode
+            parameter. For mode 'F', the array is a one dimensional array of float of size (width*height).
+   :rtype: :class:`~bgl.Buffer`
+
+.. function:: materialID(object, name)
 
    Returns a numeric value that can be used in :class:`Texture` to create a dynamic texture.
 
    The value corresponds to an internal material number that uses the texture identified
-   by name. name is a string representing a texture name with IM prefix if you want to
-   identify the texture directly.    This method works for basic tex face and for material,
+   by name. name is a string representing a texture name with ``IM`` prefix if you want to
+   identify the texture directly. This method works for basic tex face and for material,
    provided the material has a texture channel using that particular texture in first
-   position of the texture stack.    name can also have MA prefix if you want to identify
+   position of the texture stack. name can also have ``MA`` prefix if you want to identify
    the texture by material. In that case the material must have a texture channel in first
    position.
 
    If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
 
-   Ex: bge.texture.materialID(obj, 'IMvideo.png')
+   Ex: ``bge.texture.materialID(obj, 'IMvideo.png')``
 
-   :arg object: the game object that uses the texture you want to make dynamic
-   :type object: game object
-   :arg name: name of the texture/material you want to make dynamic.
-   :type name: string
-   :rtype: integer
+   :arg object: The game object that uses the texture you want to make dynamic.
+   :type object: :class:`~bge.types.KX_GameObject`
+   :arg name: Name of the texture/material you want to make dynamic.
+   :type name: str
+   
+   :return: The internal material number.
+   :rtype: int
 
 .. function:: setLogFile(filename)
 
@@ -579,6 +1089,151 @@ When the texture object is deleted, the new texture is deleted and the old textu
    of the messages on the Python console. Only the runtime errors specific to the VideoTexture module
    are written in that file, ordinary runtime time errors are not written.
 
-   :arg filename: name of error log file
-   :type filename: string
-   :rtype: integer
+   :arg filename: Name of the error log file.
+   :type filename: str
+   
+   :return: -1 if the parameter name is invalid (not of type string), else 0.
+   :rtype: int
+
+   
+*********
+Constants
+*********
+
+FFmpeg video and image statuses
++++++++++++++++++++++++++++++++
+
+
+.. data:: SOURCE_ERROR
+
+   :type: int
+
+.. data:: SOURCE_EMPTY
+
+   :type: int
+
+.. data:: SOURCE_READY
+
+   :type: int
+
+.. data:: SOURCE_PLAYING
+
+   :type: int
+
+.. data:: SOURCE_STOPPED
+
+   :type: int
+
+
+Image blending modes
+++++++++++++++++++++
+
+See Wikipedia's `Blend Modes <https://en.wikipedia.org/wiki/Blend_modes>`_ for reference.
+
+.. data:: IMB_BLEND_MIX
+
+   :type: int
+
+.. data:: IMB_BLEND_ADD
+
+   :type: int
+
+.. data:: IMB_BLEND_SUB
+
+   :type: int
+
+.. data:: IMB_BLEND_MUL
+
+   :type: int
+
+.. data:: IMB_BLEND_LIGHTEN
+
+   :type: int
+
+.. data:: IMB_BLEND_DARKEN
+
+   :type: int
+
+.. data:: IMB_BLEND_ERASE_ALPHA
+
+   :type: int
+
+.. data:: IMB_BLEND_ADD_ALPHA
+
+   :type: int
+
+.. data:: IMB_BLEND_OVERLAY
+
+   :type: int
+
+.. data:: IMB_BLEND_HARDLIGHT
+
+   :type: int
+
+.. data:: IMB_BLEND_COLORBURN
+
+   :type: int
+
+.. data:: IMB_BLEND_LINEARBURN
+
+   :type: int
+
+.. data:: IMB_BLEND_COLORDODGE
+
+   :type: int
+
+.. data:: IMB_BLEND_SCREEN
+
+   :type: int
+
+.. data:: IMB_BLEND_SOFTLIGHT
+
+   :type: int
+
+.. data:: IMB_BLEND_PINLIGHT
+
+   :type: int
+
+.. data:: IMB_BLEND_VIVIDLIGHT
+
+   :type: int
+
+.. data:: IMB_BLEND_LINEARLIGHT
+
+   :type: int
+
+.. data:: IMB_BLEND_DIFFERENCE
+
+   :type: int
+
+.. data:: IMB_BLEND_EXCLUSION
+
+   :type: int
+
+.. data:: IMB_BLEND_HUE
+
+   :type: int
+
+.. data:: IMB_BLEND_SATURATION
+
+   :type: int
+
+.. data:: IMB_BLEND_LUMINOSITY
+
+   :type: int
+
+.. data:: IMB_BLEND_COLOR
+
+   :type: int
+
+.. data:: IMB_BLEND_COPY
+
+   :type: int
+
+.. data:: IMB_BLEND_COPY_RGB
+
+   :type: int
+
+.. data:: IMB_BLEND_COPY_ALPHA
+
+   :type: int