[Bf-blender-cvs] [6ed1a1a] master: BGE: bge.texture API documentation enhancement

Quentin Wenger noreply at git.blender.org
Mon Jul 6 21:49:16 CEST 2015


Commit: 6ed1a1abe23fcff887ab0da070ee44d9e16b385e
Author: Quentin Wenger
Date:   Mon Jul 6 11:11:40 2015 +0200
Branches: master
https://developer.blender.org/rB6ed1a1abe23fcff887ab0da070ee44d9e16b385e

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

===================================================================

M	doc/python_api/examples/bge.texture.1.py
M	doc/python_api/examples/bge.texture.py
M	doc/python_api/rst/bge.texture.rst
M	source/gameengine/VideoTexture/blendVideoTex.cpp

===================================================================

diff --git a/doc/python_api/examples/bge.texture.1.py b/doc/python_api/examples/bge.texture.1.py
index fba3697..bee1f25 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 1ba0b99..ac1f5a2 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 dde2661..90d56c9 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)
-
-   

@@ Diff output truncated at 10240 characters. @@




More information about the Bf-blender-cvs mailing list