griefith/test2
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

BGE: bge.texture API documentation enhancement

Browse Source 
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
This commit is contained in:
Quentin Wenger
2015-07-06 11:11:40 +02:00
committed by Porteries Tristan
parent 791b5fe9d0
commit 6ed1a1abe2
4 changed files with 886 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/python_api/examples/bge.texture.1.py
View File

@@ -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

3
doc/python_api/examples/bge.texture.py
View File

@@ -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

1037
doc/python_api/rst/bge.texture.rst
View File

@@ -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-
*************
Video classes
*************
.. class:: VideoFFmpeg(file [, capture=-1, rate=25.0, width=0, height=0])
.. class:: VideoFFmpeg(file, capture=-1, rate=25.0, width=0, height=0)
FFmpeg video source
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
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])
.. method:: reload(newname=None)
Reload image, i.e. reopen it
Reload image, i.e. reopen it.
:arg newname: Path to a new image. (optional)
:type newname: str
.. class:: ImageBuff()
.. class:: ImageBuff(width, height, color=0, scale=False)
Image source from image buffer
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
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)
.. method:: plot(imageBuffer, width, height, positionX, positionY, mode=IMB_BLEND_COPY)
update image buffer
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)
.. class:: ImageMirror(scene)
:type: bool
Image source from mirror
.. class:: ImageMirror(scene, observer, mirror, material=0)
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
Flip image vertically.
:type: bool
.. method:: getSource(imageMix)
.. method:: getSource(id)
get image source
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(imageMix)
get image source weight
.. 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)
Fast scale of image (near neighbour).
:type: bool
.. attribute:: size
.. method:: setSource(imageMix)
Image size. (readonly)
:type: tuple of two ints
set image source
.. method:: setSource(id, image)
.. method:: setWeight(imageMix)
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`
set image source weight
.. 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
.. class:: Texture(gameObj)
***************
Texture classes
***************
Texture objects
.. class:: Texture(gameObj, materialID=0, textureID=0, textureObj=None)
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
Previous pixel filter.
:type: one of...
* :class:`FilterBGR24`
* :class:`FilterBlueScreen`
* :class:`FilterColor`
* :class:`FilterGray`
* :class:`FilterLevel`
* :class:`FilterNormal`
* :class:`FilterRGB24`
* :class:`FilterRGBA32`
.. class:: FilterLevel()
.. class:: FilterLevel
Filter for levels calculations
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
Previous pixel filter.
:type: one of...
* :class:`FilterBGR24`
* :class:`FilterBlueScreen`
* :class:`FilterColor`
* :class:`FilterGray`
* :class:`FilterLevel`
* :class:`FilterNormal`
* :class:`FilterRGB24`
* :class:`FilterRGBA32`
.. class:: FilterRGB24()
.. 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.
to the :meth:`ImageBuff.load` function has the 3-bytes pixel format BGR.
.. class:: FilterRGBA32()
.. class:: FilterRGBA32
Source filter RGBA32 objects
Source filter RGBA32.
*********
Functions
*********
.. function:: getLastError()
Last error that occurred in a bge.texture function.
:return: the description of the last error occurred in a bge.texture function.
:rtype: string
:return: The description of the last error occurred in a bge.texture function.
:rtype: str
.. function:: imageToArray(image,mode)
.. function:: imageToArray(image, mode)
Returns a :class:`~bgl.buffer` corresponding to the current image stored in a texture source object.
Returns a :class:`~bgl.Buffer` corresponding to the current image stored in a texture source object.
: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".
:arg image: Image source object of type ...
: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).
* :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)
.. 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