[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