Commit: 108b2f820727219d1d8e5faf1613b4f7dd0911bb Author: Quentin Wenger Date: Mon Jul 6 11:11:40 2015 +0200 Branches: init https://developer.blender.org/rB108b2f820727219d1d8e5faf1613b4f7dd0911bb
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. @@ _______________________________________________ Bf-blender-cvs mailing list [email protected] http://lists.blender.org/mailman/listinfo/bf-blender-cvs
