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_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).

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

Table Of Contents

Previous topic

Rasterizer (bge.render)

Next topic

Game Keys (bge.events)