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:

* 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.

Basic Video Playback
++++++++++++++++++++
Example of how to replace a texture in game with a video. It needs to run everyframe

import bge
from bge import texture
from bge import logic

cont = logic.getCurrentController()
obj = cont.owner

# the creation of the texture must be done once: save the
# texture object in an attribute of bge.logic module makes it persistent
if not hasattr(logic, 'video'):

    # identify a static texture by name
    matID = texture.materialID(obj, 'IMvideo.png')

    # create a dynamic texture that will replace the static texture
    logic.video = texture.Texture(obj, matID)

    # define a source of image for the texture, here a movie
    movie = logic.expandPath('//trailer_400p.ogg')
    logic.video.source = texture.VideoFFmpeg(movie)
    logic.video.source.scale = True

    # 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.
logic.video.refresh(True)

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.

from bge import logic
from bge import texture


def createTexture(cont):
    """Create a new Dynamic Texture"""
    obj = cont.owner

    # get the reference pointer (ID) of the internal texture
    ID = texture.materialID(obj, 'IMoriginal.png')

    # create a texture object
    object_texture = texture.Texture(obj, ID)

    # create a new source with an external image
    url = logic.expandPath("//newtexture.jpg")
    new_source = texture.ImageFFmpeg(url)

    # the texture has to be stored in a permanent Python object
    logic.texture = object_texture

    # update/replace the texture
    logic.texture.source = new_source
    logic.texture.refresh(False)


def removeTexture(cont):
    """Delete the Dynamic Texture, reversing back the final to its original state."""
    try:
        del logic.texture
    except:
        pass

class bge.texture.VideoFFmpeg(file[, capture=-1, rate=25.0, width=0, height=0])¶

FFmpeg video source

status¶: video status

range¶: replay range

repeat¶

repeat count, -1 for infinite repeat

Type:	int

framerate¶

frame rate

Type:	float

valid¶

Tells if an image is available

Type:	bool

image¶: image data

size¶: image size

scale¶: fast scale of image (near neighbour)

flip¶: flip image vertically

filter¶: pixel filter

preseek¶

number of frames of preseek

Type:	int

deinterlace¶

deinterlace image

Type:	bool

play()¶: Play (restart) video

pause()¶: pause video

stop()¶: stop video (play will replay it from start)

refresh()¶: Refresh video - get its status

class bge.texture.ImageFFmpeg(file)¶

FFmpeg image source

status¶: video status

valid¶

Tells if an image is available

Type:	bool

image¶: image data

size¶: image size

scale¶: fast scale of image (near neighbour)

flip¶: flip image vertically

filter¶: pixel filter

refresh()¶: Refresh image, i.e. load it

reload([newname])¶: Reload image, i.e. reopen it

class bge.texture.ImageBuff¶

Image source from image buffer

filter¶: pixel filter

flip¶: flip image vertically

image¶: image data

load(imageBuffer, width, height)¶: Load image from buffer

plot(imageBuffer, width, height, positionX, positionY)¶: update image buffer

scale¶: fast scale of image (near neighbour)

size¶: image size

valid¶: bool to tell if an image is available

class bge.texture.ImageMirror(scene)¶

Image source from mirror

alpha¶: use alpha in texture

background¶: background color

capsize¶: size of render area

clip¶: clipping distance

filter¶: pixel filter

flip¶: flip image vertically

image¶: image data

refresh(imageMirror)¶: Refresh image - invalidate its current content

scale¶: fast scale of image (near neighbour)

size¶: image size

valid¶: bool to tell if an image is available

whole¶: use whole viewport to render

class bge.texture.ImageMix¶

Image mixer

filter¶: pixel filter

flip¶: flip image vertically

getSource(imageMix)¶: get image source

getWeight(imageMix)¶: get image source weight

image¶: image data

refresh(imageMix)¶: Refresh image - invalidate its current content

scale¶: fast scale of image (near neighbour)

setSource(imageMix)¶: set image source

setWeight(imageMix)¶: set image source weight

valid¶: bool to tell if an image is available

class bge.texture.ImageRender(scene, camera)¶

Image source from render

alpha¶: use alpha in texture

background¶: background color

capsize¶: size of render area

filter¶: pixel filter

flip¶: flip image vertically

image¶: image data

refresh(imageRender)¶: Refresh image - invalidate its current content

scale¶: fast scale of image (near neighbour)

size¶: image size

valid¶: bool to tell if an image is available

whole¶: use whole viewport to render

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’)

zbuff¶: use depth component of render as grey scale color - suitable for texture source

class bge.texture.ImageViewport¶

Image source from viewport

alpha¶: use alpha in texture

capsize¶: size of viewport area being captured

filter¶: pixel filter

flip¶: flip image vertically

image¶: image data

position¶: upper left corner of captured area

refresh(imageViewport)¶: Refresh image - invalidate its current content

scale¶: fast scale of image (near neighbour)

size¶: image size

valid¶: bool to tell if an image is available

whole¶: use whole viewport to capture

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’)

zbuff¶: use depth component of viewport as grey scale color - suitable for texture source

class bge.texture.Texture(gameObj)¶

Texture objects

bindId¶: OpenGL Bind Name

close(texture)¶: Close dynamic texture and restore original

mipmap¶: mipmap texture

refresh(texture)¶: Refresh texture from source

source¶: source of texture

class bge.texture.FilterBGR24¶: Source filter BGR24 objects

class bge.texture.FilterBlueScreen¶

Filter for Blue Screen objects

color¶: blue screen color

limits¶: blue screen color limits

previous¶: previous pixel filter

class bge.texture.FilterColor¶

Filter for color calculations

matrix¶: matrix [4][5] for color calculation

previous¶: previous pixel filter

class bge.texture.FilterGray¶

Filter for gray scale effect

previous¶: previous pixel filter

class bge.texture.FilterLevel¶

Filter for levels calculations

levels¶: levels matrix [4] (min, max)

previous¶: previous pixel filter

class bge.texture.FilterNormal¶

Filter for Blue Screen objects

colorIdx¶: index of color used to calculate normal (0 - red, 1 - green, 2 - blue)

depth¶: depth of relief

previous¶: previous pixel filter

class bge.texture.FilterRGB24¶: Returns a new input filter object to be used with ImageBuff object when the image passed to the ImageBuff.load() function has the 3-bytes pixel format BGR.

class bge.texture.FilterRGBA32¶: Source filter RGBA32 objects

bge.texture.getLastError()¶

Last error that occurred in a bge.texture function.

Returns:	the description of the last error occurred in a bge.texture function.
Return type:	string

bge.texture.imageToArray(image, mode)¶

Returns a buffer corresponding to the current image stored in a texture source object.

Parameters:	image (object of type `VideoFFmpeg`, `ImageFFmpeg`, `ImageBuff`, `ImageMix`, `ImageRender`, `ImageMirror` or `ImageViewport`) – Image source object. mode (string) – 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”.
Return type:	`buffer`
Returns:	A object representing the image as one dimensional array of bytes of size (pixel_sizewidthheight), 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).

bge.texture.materialID(object, name)¶

Returns a numeric value that can be used in 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.

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’)

Parameters:	object (game object) – the game object that uses the texture you want to make dynamic name (string) – name of the texture/material you want to make dynamic.
Return type:	integer

bge.texture.setLogFile(filename)¶

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.

Parameters:	filename (string) – name of error log file
Return type:	integer

Video Texture (bge.texture)¶

Intro¶

Table Of Contents

Previous topic

Next topic