[Bf-blender-cvs] [ee2aa319821] master: PyDoc: Merge manual docs for bge.texture
Aaron Carlisle
noreply at git.blender.org
Fri Mar 30 00:02:14 CEST 2018
Commit: ee2aa319821fdf8be869fc2800711d01b6350f41
Author: Aaron Carlisle
Date: Thu Mar 29 18:02:04 2018 -0400
Branches: master
https://developer.blender.org/rBee2aa319821fdf8be869fc2800711d01b6350f41
PyDoc: Merge manual docs for bge.texture
https://docs.blender.org/manual/en/dev/game_engine/python_api/videotexture.html
Had a few things that this file did not while this file having things the other did not.
To fix, I merged both documents into the python api.
===================================================================
M doc/python_api/examples/bge.texture.py
M doc/python_api/rst/bge.texture.rst
===================================================================
diff --git a/doc/python_api/examples/bge.texture.py b/doc/python_api/examples/bge.texture.py
index ac1f5a21447..8b24530b10a 100644
--- a/doc/python_api/examples/bge.texture.py
+++ b/doc/python_api/examples/bge.texture.py
@@ -1,8 +1,11 @@
"""
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.
+To avoid any confusion with the location of the file,
+we will use ``GameLogic.expandPath()`` to build an absolute file name,
+assuming the video file is in the same directory as the blend-file.
"""
import bge
from bge import texture
@@ -26,8 +29,18 @@ if not hasattr(logic, 'video'):
logic.video.source = texture.VideoFFmpeg(movie)
logic.video.source.scale = True
+ # Note that we can change the ``Texture`` source at any time.
+ # Suppose we want to switch between two movies during the game:
+ logic.mySources[0] = texture.VideoFFmpeg('movie1.avi')
+ logic.mySources[1] = texture.VideoFFmpeg('movie2.avi')
+
+ #And then assign (and reassign) the source during the game
+ logic.video.source = logic.mySources[movieSel]
+
# quick off the movie, but it wont play in the background
logic.video.source.play()
-# you need to call this function every frame to ensure update of the texture.
+
+# Video playback is not a background process: it happens only when we refresh the texture.
+# So you need to call this function every frame to ensure update of the texture.
logic.video.refresh(True)
diff --git a/doc/python_api/rst/bge.texture.rst b/doc/python_api/rst/bge.texture.rst
index 3028ee653f8..cd99cde0bc8 100644
--- a/doc/python_api/rst/bge.texture.rst
+++ b/doc/python_api/rst/bge.texture.rst
@@ -6,18 +6,15 @@ Video Texture (bge.texture)
Introduction
************
-The bge.texture module allows you to manipulate textures during the game.
-
-Several sources for texture are possible: video files, image files, video capture, memory buffer,
-camera render or a mix of that.
-
-The video and image files can be loaded from the internet using an URL instead of a file name.
-
-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:
+The ``bge.texture`` module allows you to manipulate textures during the game.
+Several sources for texture are possible: video files, image files, video capture,
+memory buffer, camera render or a mix of that.
+The video and image files can be loaded from the Internet using a URL instead of a file name.
+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 ``bge.texture``,
+including but not limited to:
* AVI
* Ogg
@@ -28,16 +25,45 @@ All the formats and codecs that FFmpeg supports are supported by this module, in
* videoForWindows capture card (this includes many webcams)
* JPG
-The principle is simple: first you identify a texture on an existing object using
-the :class:`~bge.texture.materialID` function, then you create a new texture with dynamic content
+
+How it works
+------------
+
+The principle is simple: first you identify a texture on an existing object using 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,
+The game engine is not aware of the substitution and continues to display the object as always,
except that you are now in control of the texture.
When the texture object is deleted, the new texture is deleted and the old texture restored.
-.. module:: bge.texture
+
+Game Preparation
+----------------
+
+Before you can use the :mod:`bge.texture` module,
+you must have objects with textures applied appropriately.
+
+Imagine you want to have a television showing live broadcast programs in the game.
+You will create a television object and UV-apply a different texture at the place of the screen,
+for example ``tv.png``. What this texture looks like is not important;
+probably you want to make it dark gray to simulate power-off state.
+When the television must be turned on, you create a dynamic texture from a video capture card
+and use it instead of ``tv.png``: the TV screen will come to life.
+
+You have two ways to define textures that ``bge.texture`` can grab:
+
+- Simple UV texture.
+- Blender material with image texture channel.
+
+Because ``bge.texture`` works at texture level, it is compatible with all
+the Blender Game Engine's fancy texturing features: GLSL, multi-texture, custom shaders, etc.
+
+
+********
+Examples
+********
.. include:: __/examples/bge.texture.py
:start-line: 1
@@ -53,7 +79,6 @@ When the texture object is deleted, the new texture is deleted and the old textu
.. literalinclude:: __/examples/bge.texture.1.py
:lines: 8-
-
.. include:: __/examples/bge.texture.2.py
:start-line: 1
:end-line: 6
@@ -62,13 +87,15 @@ When the texture object is deleted, the new texture is deleted and the old textu
:lines: 8-
+.. module:: bge.texture
+
*************
Video classes
*************
.. class:: VideoFFmpeg(file, capture=-1, rate=25.0, width=0, height=0)
- FFmpeg video source.
+ FFmpeg video source, used for video files, video captures, or video streams.
:arg file: Path to the video to load; if capture >= 0 on Windows, this parameter will not be used.
:type file: str
@@ -90,19 +117,20 @@ Video classes
.. attribute:: range
- Replay range.
+ The start and stop time of the video playback, expressed in seconds from beginning.
+ By default the entire video.
:type: sequence of two floats
.. attribute:: repeat
- Repeat count, -1 for infinite repeat.
+ Number of times to replay the video, -1 for infinite repeat.
:type: int
.. attribute:: framerate
- Frame rate.
+ Relative frame rate, <1.0 for slow, >1.0 for fast.
:type: float
@@ -126,21 +154,26 @@ Video classes
.. attribute:: scale
- Fast scale of image (near neighbour).
+ Set to True to activate fast nearest neighbor scaling algorithm.
+ Texture width and height must be a power of 2.
+ If the video picture size is not a power of 2, rescaling is required.
+ By default ``bge.texture`` uses the precise but slow ``gluScaleImage()`` function.
+ Best is to rescale the video offline so that no scaling is necessary at runtime!
:type: bool
.. attribute:: flip
- Flip image vertically.
+ If True the imaged will be flipped vertically.
+ FFmpeg always delivers the image upside down, so this attribute is set to True by default.
:type: bool
.. attribute:: filter
- Pixel filter.
+ An additional filter that is applied on the video before sending it to the GPU.
- :type: one of...
+ :type: one of:
* :class:`FilterBGR24`
* :class:`FilterBlueScreen`
@@ -207,7 +240,7 @@ Image classes
.. class:: ImageFFmpeg(file)
- FFmpeg image source.
+ FFmpeg image source, used for image files and web based images.
:arg file: Path to the image to load.
:type file: str
@@ -286,7 +319,8 @@ Image classes
.. class:: ImageBuff(width, height, color=0, scale=False)
- Image source from image buffer.
+ Image from application memory.
+ For computer generated images, drawing applications.
:arg width: Width of the image.
:type width: int
@@ -477,7 +511,7 @@ Image classes
.. class:: ImageMix
- Image mixer.
+ Image mixer used to mix multiple image sources together.
.. attribute:: filter
@@ -592,7 +626,7 @@ Image classes
.. class:: ImageRender(scene, camera)
- Image source from render.
+ Image source from a render of a non active camera.
The render is done on a custom framebuffer object if fbo is specified,
otherwise on the default framebuffer.
@@ -723,7 +757,8 @@ Image classes
.. class:: ImageViewport
- Image source from viewport.
+ Image source from viewport rendered by the active camera.
+ To render from a non active camera see :class:`ImageRender`.
.. attribute:: alpha
@@ -774,11 +809,10 @@ Image classes
Refresh video - copy the viewport to an external buffer (optional) then invalidate its current content.
- :arg buffer: An optional object that implements the buffer protocol.
- If specified, the image is copied to the buffer, which must be big enough or an exception is thrown.
- The transfer to the buffer is optimal if no processing of the image is needed.
- This is the case if ``flip=False, alpha=True, scale=False, whole=True, depth=False, zbuff=False``
- and no filter is set.
+ :arg buffer: An optional object that implements the buffer protocol. If specified,
+ the image is copied to the buffer, which must be big enough or an exception is thrown.
+ The transfer to the buffer is optimal if no processing of the image is needed. This is the case if
+ ``flip=False, alpha=True, scale=False, whole=True, depth=False, zbuff=False`` and no filter is set.
:type buffer: any buffer type
:arg format: An optional image format specifier for the image that will be copied to the buffer.
Only valid values are "RGBA" or "BGRA"
@@ -838,18 +872,16 @@ Image classes
:arg capture: Card number from which the input video must be captured.
:type capture: int
- The format argument must be written as ``<displayMode>/<pixelFormat>[/3D][:<cacheSize>]`` where ``<displayMode>``
- describes the frame size and rate and <pixelFormat> the encoding of the pixels.
+ The format argument must be written as ``<displayMode>/<pixelFormat>[/3
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list