blender/doc/python_api/rst/bge.texture.rst

560 lines
11 KiB
ReStructuredText
Raw Normal View History

Video Texture (bge.texture)
===========================
*****
Intro
*****
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::
2011-07-07 19:23:51 +00:00
* AVI
* Ogg
* Xvid
* Theora
* dv1394 camera
* video4linux capture card (this includes many webcams)
* videoForWindows capture card (this includes many webcams)
* 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
and swap the two textures in the GPU.
The GE 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
.. 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
.. literalinclude:: ../examples/bge.texture.1.py
:lines: 8-
.. class:: VideoFFmpeg(file [, capture=-1, rate=25.0, width=0, height=0])
2011-07-07 19:23:51 +00:00
FFmpeg video source
2011-07-07 19:23:51 +00:00
.. attribute:: status
2011-07-07 19:23:51 +00:00
video status
.. attribute:: range
2011-07-07 19:23:51 +00:00
replay range
2011-07-07 19:23:51 +00:00
.. attribute:: repeat
2011-07-07 19:23:51 +00:00
repeat count, -1 for infinite repeat
2011-07-07 19:23:51 +00:00
:type: int
2011-07-07 19:23:51 +00:00
.. attribute:: framerate
2011-07-07 19:23:51 +00:00
frame rate
2011-07-07 19:23:51 +00:00
:type: float
2011-07-07 19:23:51 +00:00
.. attribute:: valid
2011-07-07 19:23:51 +00:00
Tells if an image is available
2011-07-07 19:23:51 +00:00
:type: bool
2011-07-07 19:23:51 +00:00
.. attribute:: image
2011-07-07 19:23:51 +00:00
image data
2011-07-07 19:23:51 +00:00
.. attribute:: size
2011-07-07 19:23:51 +00:00
image size
2011-07-07 19:23:51 +00:00
.. attribute:: scale
2011-07-07 19:23:51 +00:00
fast scale of image (near neighbour)
2011-07-07 19:23:51 +00:00
.. attribute:: flip
2011-07-07 19:23:51 +00:00
flip image vertically
2011-07-07 19:23:51 +00:00
.. attribute:: filter
2011-07-07 19:23:51 +00:00
pixel filter
2011-07-07 19:23:51 +00:00
.. attribute:: preseek
2011-07-07 19:23:51 +00:00
number of frames of preseek
2011-07-07 19:23:51 +00:00
:type: int
2011-07-07 19:23:51 +00:00
.. attribute:: deinterlace
2011-07-07 19:23:51 +00:00
deinterlace image
2011-07-07 19:23:51 +00:00
:type: bool
2011-07-07 19:23:51 +00:00
.. method:: play()
2011-07-07 19:23:51 +00:00
Play (restart) video
2011-07-07 19:23:51 +00:00
.. method:: pause()
2011-07-07 19:23:51 +00:00
pause video
2011-07-07 19:23:51 +00:00
.. method:: stop()
2011-07-07 19:23:51 +00:00
stop video (play will replay it from start)
2011-07-07 19:23:51 +00:00
.. method:: refresh()
2011-07-07 19:23:51 +00:00
Refresh video - get its status
.. class:: ImageFFmpeg(file)
2011-07-07 19:23:51 +00:00
FFmpeg image source
2011-07-07 19:23:51 +00:00
.. attribute:: status
2011-07-07 19:23:51 +00:00
video status
2011-07-07 19:23:51 +00:00
.. attribute:: valid
2011-07-07 19:23:51 +00:00
Tells if an image is available
2011-07-07 19:23:51 +00:00
:type: bool
2011-07-07 19:23:51 +00:00
.. attribute:: image
2011-07-07 19:23:51 +00:00
image data
2011-07-07 19:23:51 +00:00
.. attribute:: size
2011-07-07 19:23:51 +00:00
image size
2011-07-07 19:23:51 +00:00
.. attribute:: scale
2011-07-07 19:23:51 +00:00
fast scale of image (near neighbour)
2011-07-07 19:23:51 +00:00
.. attribute:: flip
2011-07-07 19:23:51 +00:00
flip image vertically
2011-07-07 19:23:51 +00:00
.. attribute:: filter
2011-07-07 19:23:51 +00:00
pixel filter
2011-07-07 19:23:51 +00:00
.. method:: refresh()
2011-07-07 19:23:51 +00:00
Refresh image, i.e. load it
2011-07-07 19:23:51 +00:00
.. method:: reload([newname])
2011-07-07 19:23:51 +00:00
Reload image, i.e. reopen it
.. class:: ImageBuff()
2011-07-07 19:23:51 +00:00
Image source from image buffer
2011-07-07 19:23:51 +00:00
.. attribute:: filter
2011-07-07 19:23:51 +00:00
pixel filter
2011-07-07 19:23:51 +00:00
.. attribute:: flip
2011-07-07 19:23:51 +00:00
flip image vertically
2011-07-07 19:23:51 +00:00
.. attribute:: image
2011-07-07 19:23:51 +00:00
image data
2011-07-07 19:23:51 +00:00
.. method:: load(imageBuffer, width, height)
2011-07-07 19:23:51 +00:00
Load image from buffer
2011-07-07 19:23:51 +00:00
.. method:: plot(imageBuffer, width, height, positionX, positionY)
2011-07-07 19:23:51 +00:00
update image buffer
2011-07-07 19:23:51 +00:00
.. attribute:: scale
2011-07-07 19:23:51 +00:00
fast scale of image (near neighbour)
2011-07-07 19:23:51 +00:00
.. attribute:: size
2011-07-07 19:23:51 +00:00
image size
2011-07-07 19:23:51 +00:00
.. attribute:: valid
2011-07-07 19:23:51 +00:00
bool to tell if an image is available
.. class:: ImageMirror(scene)
2011-07-07 19:23:51 +00:00
Image source from mirror
2011-07-07 19:23:51 +00:00
.. attribute:: alpha
2011-07-07 19:23:51 +00:00
use alpha in texture
2011-07-07 19:23:51 +00:00
.. attribute:: background
2011-07-07 19:23:51 +00:00
background color
2011-07-07 19:23:51 +00:00
.. attribute:: capsize
2011-07-07 19:23:51 +00:00
size of render area
2011-07-07 19:23:51 +00:00
.. attribute:: clip
2011-07-07 19:23:51 +00:00
clipping distance
2011-07-07 19:23:51 +00:00
.. attribute:: filter
2011-07-07 19:23:51 +00:00
pixel filter
2011-07-07 19:23:51 +00:00
.. attribute:: flip
2011-07-07 19:23:51 +00:00
flip image vertically
2011-07-07 19:23:51 +00:00
.. attribute:: image
2011-07-07 19:23:51 +00:00
image data
2011-07-07 19:23:51 +00:00
.. method:: refresh(imageMirror)
2011-07-07 19:23:51 +00:00
Refresh image - invalidate its current content
2011-07-07 19:23:51 +00:00
.. attribute:: scale
2011-07-07 19:23:51 +00:00
fast scale of image (near neighbour)
2011-07-07 19:23:51 +00:00
.. attribute:: size
2011-07-07 19:23:51 +00:00
image size
2011-07-07 19:23:51 +00:00
.. attribute:: valid
2011-07-07 19:23:51 +00:00
bool to tell if an image is available
2011-07-07 19:23:51 +00:00
.. attribute:: whole
2011-07-07 19:23:51 +00:00
use whole viewport to render
.. class:: ImageMix()
2011-07-07 19:23:51 +00:00
Image mixer
2011-07-07 19:23:51 +00:00
.. attribute:: filter
2011-07-07 19:23:51 +00:00
pixel filter
2011-07-07 19:23:51 +00:00
.. attribute:: flip
2011-07-07 19:23:51 +00:00
flip image vertically
2011-07-07 19:23:51 +00:00
.. method:: getSource(imageMix)
2011-07-07 19:23:51 +00:00
get image source
2011-07-07 19:23:51 +00:00
.. method:: getWeight(imageMix)
2011-07-07 19:23:51 +00:00
get image source weight
2011-07-07 19:23:51 +00:00
.. attribute:: image
2011-07-07 19:23:51 +00:00
image data
2011-07-07 19:23:51 +00:00
.. method:: refresh(imageMix)
2011-07-07 19:23:51 +00:00
Refresh image - invalidate its current content
2011-07-07 19:23:51 +00:00
.. attribute:: scale
2011-07-07 19:23:51 +00:00
fast scale of image (near neighbour)
2011-07-07 19:23:51 +00:00
.. method:: setSource(imageMix)
2011-07-07 19:23:51 +00:00
set image source
2011-07-07 19:23:51 +00:00
.. method:: setWeight(imageMix)
2011-07-07 19:23:51 +00:00
set image source weight
2011-07-07 19:23:51 +00:00
.. attribute:: valid
2011-07-07 19:23:51 +00:00
bool to tell if an image is available
.. class:: ImageRender(scene, camera)
2011-07-07 19:23:51 +00:00
Image source from render
2011-07-07 19:23:51 +00:00
.. attribute:: alpha
2011-07-07 19:23:51 +00:00
use alpha in texture
2011-07-07 19:23:51 +00:00
.. attribute:: background
2011-07-07 19:23:51 +00:00
background color
2011-07-07 19:23:51 +00:00
.. attribute:: capsize
2011-07-07 19:23:51 +00:00
size of render area
2011-07-07 19:23:51 +00:00
.. attribute:: filter
2011-07-07 19:23:51 +00:00
pixel filter
2011-07-07 19:23:51 +00:00
.. attribute:: flip
2011-07-07 19:23:51 +00:00
flip image vertically
2011-07-07 19:23:51 +00:00
.. attribute:: image
2011-07-07 19:23:51 +00:00
image data
2011-07-07 19:23:51 +00:00
.. method:: refresh(imageRender)
2011-07-07 19:23:51 +00:00
Refresh image - invalidate its current content
2011-07-07 19:23:51 +00:00
.. attribute:: scale
2011-07-07 19:23:51 +00:00
fast scale of image (near neighbour)
2011-07-07 19:23:51 +00:00
.. attribute:: size
2011-07-07 19:23:51 +00:00
image size
2011-07-07 19:23:51 +00:00
.. attribute:: valid
2011-07-07 19:23:51 +00:00
bool to tell if an image is available
2011-07-07 19:23:51 +00:00
.. attribute:: whole
2011-07-07 19:23:51 +00:00
use whole viewport to render
.. class:: ImageViewport()
2011-07-07 19:23:51 +00:00
Image source from viewport
2011-07-07 19:23:51 +00:00
.. attribute:: alpha
2011-07-07 19:23:51 +00:00
use alpha in texture
2011-07-07 19:23:51 +00:00
.. attribute:: capsize
2011-07-07 19:23:51 +00:00
size of viewport area being captured
2011-07-07 19:23:51 +00:00
.. attribute:: filter
2011-07-07 19:23:51 +00:00
pixel filter
2011-07-07 19:23:51 +00:00
.. attribute:: flip
2011-07-07 19:23:51 +00:00
flip image vertically
2011-07-07 19:23:51 +00:00
.. attribute:: image
2011-07-07 19:23:51 +00:00
image data
2011-07-07 19:23:51 +00:00
.. attribute:: position
2011-07-07 19:23:51 +00:00
upper left corner of captured area
2011-07-07 19:23:51 +00:00
.. method:: refresh(imageViewport)
2011-07-07 19:23:51 +00:00
Refresh image - invalidate its current content
2011-07-07 19:23:51 +00:00
.. attribute:: scale
2011-07-07 19:23:51 +00:00
fast scale of image (near neighbour)
2011-07-07 19:23:51 +00:00
.. attribute:: size
2011-07-07 19:23:51 +00:00
image size
2011-07-07 19:23:51 +00:00
.. attribute:: valid
2011-07-07 19:23:51 +00:00
bool to tell if an image is available
2011-07-07 19:23:51 +00:00
.. attribute:: whole
2011-07-07 19:23:51 +00:00
use whole viewport to capture
.. class:: Texture(gameObj)
2011-07-07 19:23:51 +00:00
Texture objects
2011-07-07 19:23:51 +00:00
.. attribute:: bindId
2011-07-07 19:23:51 +00:00
OpenGL Bind Name
2011-07-07 19:23:51 +00:00
.. method:: close(texture)
2011-07-07 19:23:51 +00:00
Close dynamic texture and restore original
2011-07-07 19:23:51 +00:00
.. attribute:: mipmap
2011-07-07 19:23:51 +00:00
mipmap texture
2011-07-07 19:23:51 +00:00
.. method:: refresh(texture)
2011-07-07 19:23:51 +00:00
Refresh texture from source
2011-07-07 19:23:51 +00:00
.. attribute:: source
2011-07-07 19:23:51 +00:00
source of texture
.. class:: FilterBGR24()
2011-07-07 19:23:51 +00:00
Source filter BGR24 objects
.. class:: FilterBlueScreen()
2011-07-07 19:23:51 +00:00
Filter for Blue Screen objects
2011-07-07 19:23:51 +00:00
.. attribute:: color
2011-07-07 19:23:51 +00:00
blue screen color
2011-07-07 19:23:51 +00:00
.. attribute:: limits
2011-07-07 19:23:51 +00:00
blue screen color limits
2011-07-07 19:23:51 +00:00
.. attribute:: previous
2011-07-07 19:23:51 +00:00
previous pixel filter
.. class:: FilterColor()
2011-07-07 19:23:51 +00:00
Filter for color calculations
2011-07-07 19:23:51 +00:00
.. attribute:: matrix
2011-07-07 19:23:51 +00:00
matrix [4][5] for color calculation
2011-07-07 19:23:51 +00:00
.. attribute:: previous
2011-07-07 19:23:51 +00:00
previous pixel filter
.. class:: FilterGray()
2011-07-07 19:23:51 +00:00
Filter for gray scale effect
2011-07-07 19:23:51 +00:00
.. attribute:: previous
2011-07-07 19:23:51 +00:00
previous pixel filter
.. class:: FilterLevel()
2011-07-07 19:23:51 +00:00
Filter for levels calculations
2011-07-07 19:23:51 +00:00
.. attribute:: levels
2011-07-07 19:23:51 +00:00
levels matrix [4] (min, max)
2011-07-07 19:23:51 +00:00
.. attribute:: previous
2011-07-07 19:23:51 +00:00
previous pixel filter
.. class:: FilterNormal()
2011-07-07 19:23:51 +00:00
Filter for Blue Screen objects
2011-07-07 19:23:51 +00:00
.. attribute:: colorIdx
2011-07-07 19:23:51 +00:00
index of color used to calculate normal (0 - red, 1 - green, 2 - blue)
2011-07-07 19:23:51 +00:00
.. attribute:: depth
2011-07-07 19:23:51 +00:00
depth of relief
2011-07-07 19:23:51 +00:00
.. attribute:: previous
2011-07-07 19:23:51 +00:00
previous pixel filter
.. class:: FilterRGB24()
2011-07-07 19:23:51 +00:00
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.
.. class:: FilterRGBA32()
2011-07-07 19:23:51 +00:00
Source filter RGBA32 objects
.. function:: getLastError()
2011-07-07 19:23:51 +00:00
Last error that occurred in a bge.texture function.
2011-07-07 19:23:51 +00:00
:return: the description of the last error occurred in a bge.texture function.
:rtype: string
.. function:: imageToArray(image,mode)
2011-07-07 19:23:51 +00:00
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,
2011-07-07 19:23:51 +00:00
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.
2011-07-07 19:23:51 +00:00
"RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
The default mode is "RGBA".
: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
2011-07-07 19:23:51 +00:00
parameter.
.. function:: materialID(object,name)
2011-07-07 19:23:51 +00:00
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,
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
the texture by material. In that case the material must have a texture channel in first
position.
2011-07-07 19:23:51 +00:00
If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
2011-07-07 19:23:51 +00:00
Ex: bge.texture.materialID(obj, 'IMvideo.png')
2011-07-07 19:23:51 +00:00
: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.
2011-07-07 19:23:51 +00:00
:type name: string
:rtype: integer
.. function:: setLogFile(filename)
2011-07-07 19:23:51 +00:00
Sets the name of a text file in which runtime error messages will be written, in addition to the printing
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.
2011-07-07 19:23:51 +00:00
:arg filename: name of error log file
:type filename: string
:rtype: integer