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

Sphinx Warnings

39: ERROR: Error in "warning" directive:
unknown option: "start-line".

.. warning:: include not available in preview:  ../examples/bge.texture.py
   :start-line: 1
   :end-line: 5
43: ERROR: Error in "warning" directive:
unknown option: "lines".

.. warning:: include not available in preview:  ../examples/bge.texture.py
   :lines: 7-
46: ERROR: Error in "warning" directive:
unknown option: "start-line".

.. warning:: include not available in preview:  ../examples/bge.texture.1.py
   :start-line: 1
   :end-line: 6
50: ERROR: Error in "warning" directive:
unknown option: "lines".

.. warning:: include not available in preview:  ../examples/bge.texture.1.py
   :lines: 8-
689: WARNING: duplicate object description of bge.texture.ImageRender.refresh, other instance in contents, use :noindex: for one of them

Note the preview is not accurate and warnings may not indicate real issues.

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:

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

Video classes

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

FFmpeg video source.

Parameters:

• file (str) – Path to the video to load; if capture >= 0 on Windows, this parameter will not be used.

• capture (int) – Capture device number; if >= 0, the corresponding webcam will be used. (optional)

• rate (float) – Capture rate. (optional, used only if capture >= 0)

• width (int) – Capture width. (optional, used only if capture >= 0)

• height (int) – Capture height. (optional, used only if capture >= 0)

status

Video status. (readonly)

Type:

int

Value:

see FFmpeg Video and Image Status.

range

Replay range.

Type:

sequence of two floats

repeat

Repeat count, -1 for infinite repeat.

Type:

int

framerate

Frame rate.

Type:

float

valid

Tells if an image is available. (readonly)

Type:

bool

image

Image data. (readonly)

Type:

Buffer or None

size

Image size. (readonly)

Type:

tuple of two ints

scale

Fast scale of image (near neighbour).

Type:

bool

flip

Flip image vertically.

Type:

bool

filter

Pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

preseek

Number of frames of preseek.

Type:

int

deinterlace

Deinterlace image.

Type:

bool

play()

Play (restart) video.

Returns:

Whether the video was ready or stopped.

Return type:

bool

pause()

Pause video.

Returns:

Whether the video was playing.

Return type:

bool

stop()

Stop video (play will replay it from start).

Returns:

Whether the video was playing.

Return type:

bool

refresh(buffer=None, format='RGBA', timestamp=-1.0)

Refresh video - get its status and optionally copy the frame to an external buffer.

Parameters:

• buffer (any buffer type) – 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.

• format (str) – An optional image format specifier for the image that will be copied to the buffer. Only valid values are “RGBA” or “BGRA”

• timestamp (float) – An optional timestamp (in seconds from the start of the movie) of the frame to be copied to the buffer.

Returns:

see FFmpeg Video and Image Status.

Return type:

int

Image classes

class bge.texture.ImageFFmpeg(file)

FFmpeg image source.

Parameters:

file (str) – Path to the image to load.

status

Image status. (readonly)

Type:

int

Value:

see FFmpeg Video and Image Status.

valid

Tells if an image is available. (readonly)

Type:

bool

image

Image data. (readonly)

Type:

Buffer or None

size

Image size. (readonly)

Type:

tuple of two ints

scale

Fast scale of image (near neighbour).

Type:

bool

flip

Flip image vertically.

Type:

bool

filter

Pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

refresh(buffer=None, format='RGBA')

Refresh image, get its status and optionally copy the frame to an external buffer.

Parameters:

• buffer (any buffer type) – 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.

• format (str) – An optional image format specifier for the image that will be copied to the buffer. Only valid values are “RGBA” or “BGRA”

Returns:

see FFmpeg Video and Image Status.

Return type:

int

reload(newname=None)

Reload image, i.e. reopen it.

Parameters:

newname (str) – Path to a new image. (optional)

class bge.texture.ImageBuff(width, height, color=0, scale=False)

Image source from image buffer.

Parameters:

• width (int) – Width of the image.

• height (int) – Height of the image.

• color (int in [0, 255]) – Value to initialize RGB channels with. The initialized buffer will have all pixels set to (color, color, color, 255). (optional)

• scale (bool) – Image uses scaling. (optional)

filter

Pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

flip

Flip image vertically.

Type:

bool

image

Image data. (readonly)

Type:

Buffer or None

load(imageBuffer, width, height)

Load image from buffer.

Parameters:

• imageBuffer (Buffer or Python object implementing the buffer protocol (f.ex. bytes)) – Buffer to load the image from.

• width (int) – Width of the image to load.

• height (int) – Height of the image to load.

plot(imageBuffer, width, height, positionX, positionY, mode=IMB_BLEND_COPY)

Update image buffer.

Parameters:

• imageBuffer (Buffer, ImageBuff or Python object implementing the buffer protocol (f.ex. bytes)) – Buffer to load the new data from.

• width (int) – Width of the data to load.

• height (int) – Height of the data to load.

• positionX (int) – Left boundary of the region to be drawn on.

• positionY (int) – Upper boundary of the region to be drawn on.

• mode (int) – Drawing mode, see Image Blending Modes.

scale

Fast scale of image (near neighbour).

Type:

bool

size

Image size. (readonly)

Type:

tuple of two ints

valid

Tells if an image is available. (readonly)

Type:

bool

class bge.texture.ImageMirror(scene, observer, mirror, material=0)

Image source from mirror.

Parameters:

• scene (KX_Scene) – Scene in which the image has to be taken.

• observer (KX_GameObject) – Reference object for the mirror (the object from which the mirror has to be looked at, for example a camera).

• mirror (KX_GameObject) – Object holding the mirror.

• material (int) – ID of the mirror’s material to be used for mirroring. (optional)

alpha

Use alpha in texture.

Type:

bool

background

Background color.

Type:

int or float list [r, g, b, a] in [0.0, 255.0]

capsize

Size of render area.

Type:

sequence of two ints

clip

Clipping distance.

Type:

float in [0.01, 5000.0]

filter

Pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

flip

Flip image vertically.

Type:

bool

image

Image data. (readonly)

Type:

Buffer or None

refresh(buffer=None, format='RGBA')

Refresh image - render and copy the image to an external buffer (optional) then invalidate its current content.

Parameters:

• buffer (any buffer type) – An optional object that implements the buffer protocol. If specified, the image is rendered and copied to the buffer, which must be big enough or an exception is thrown.

• format (str) – An optional image format specifier for the image that will be copied to the buffer. Only valid values are “RGBA” or “BGRA”

scale

Fast scale of image (near neighbour).

Type:

bool

size

Image size (readonly).

Type:

tuple of two ints

valid

Tells if an image is available. (readonly)

Type:

bool

whole

Use whole viewport to render.

Type:

bool

class bge.texture.ImageMix

Image mixer.

filter

Pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

flip

Flip image vertically.

Type:

bool

getSource(id)

Get image source.

Parameters:

id (str) – Identifier of the source to get.

Returns:

Image source.

Return type:

one of…

• VideoFFmpeg

• ImageFFmpeg

• ImageBuff

• ImageMirror

• ImageMix

• ImageRender

• ImageViewport

getWeight(id)

Get image source weight.

Parameters:

id (str) – Identifier of the source.

Returns:

Weight of the source.

Return type:

int

image

Image data. (readonly)

Type:

Buffer or None

refresh(buffer=None, format='RGBA')

Refresh image - calculate and copy the image to an external buffer (optional) then invalidate its current content.

Parameters:

• buffer (any buffer type) – An optional object that implements the buffer protocol. If specified, the image is calculated and copied to the buffer, which must be big enough or an exception is thrown.

• format (str) – An optional image format specifier for the image that will be copied to the buffer. Only valid values are “RGBA” or “BGRA”

scale

Fast scale of image (near neighbour).

Type:

bool

size

Image size. (readonly)

Type:

tuple of two ints

setSource(id, image)

Set image source - all sources must have the same size.

Parameters:

• id (str) – Identifier of the source to set.

• image –

  Image source of type…

  • VideoFFmpeg

  • ImageFFmpeg

  • ImageBuff

  • ImageMirror

  • ImageMix

  • ImageRender

  • ImageViewport

setWeight(id, weight)

Set image source weight - the sum of the weights should be 256 to get full color intensity in the output.

Parameters:

• id (str) – Identifier of the source.

• weight (int) – Weight of the source.

valid

Tells if an image is available. (readonly)

Type:

bool

class bge.texture.ImageRender(scene, camera, fbo=None)

Image source from render. The render is done on a custom framebuffer object if fbo is specified, otherwise on the default framebuffer.

Parameters:

• scene (KX_Scene) – Scene in which the image has to be taken.

• camera (KX_Camera) – Camera from which the image has to be taken.

• fbo (RASOffScreen) – Off-screen render buffer object (optional)

alpha

Use alpha in texture.

Type:

bool

background

Background color.

Type:

int or float list [r, g, b, a] in [0.0, 255.0]

capsize

Size of render area.

Type:

sequence of two ints

filter

Pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

flip

Flip image vertically.

Type:

bool

image

Image data. (readonly)

Type:

Buffer or None

scale

Fast scale of image (near neighbour).

Type:

bool

size

Image size. (readonly)

Type:

tuple of two ints

valid

Tells if an image is available. (readonly)

Type:

bool

whole

Use whole viewport to render.

Type:

bool

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

Type:

bool

zbuff

Use depth component of render as grey scale color - suitable for texture source.

Type:

bool

render()

Render the scene but do not extract the pixels yet. The function returns as soon as the render commands have been send to the GPU. The render will proceed asynchronously in the GPU while the host can perform other tasks. To complete the render, you can either call refresh() directly of refresh the texture of which this object is the source. This method is useful to implement asynchronous render for optimal performance: call render() on frame n and refresh() on frame n+1 to give as much as time as possible to the GPU to render the frame while the game engine can perform other tasks.

Returns:

True if the render was initiated, False if the render cannot be performed (e.g. the camera is active)

Return type:

bool

refresh()

refresh(buffer, format='RGBA')

Refresh video - render and optionally copy the image to an external buffer then invalidate its current content. The render may have been started earlier with the render() method, in which case this function simply waits for the render operations to complete. When called without argument, the pixels are not extracted but the render is guaranteed to be completed when the function returns. This only makes sense with offscreen render on texture target (see offScreenCreate()).

Parameters:

• buffer (any buffer type of sufficient size) – An 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.

• format (str) – An optional image format specifier for the image that will be copied to the buffer. Only valid values are “RGBA” or “BGRA”

Returns:

True if the render is complete, False if the render cannot be performed (e.g. the camera is active)

Return type:

bool

class bge.texture.ImageViewport

Image source from viewport.

alpha

Use alpha in texture.

Type:

bool

capsize

Size of viewport area being captured.

Type:

sequence of two ints

filter

Pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

flip

Flip image vertically.

Type:

bool

image

Image data. (readonly)

Type:

Buffer or None

position

Upper left corner of the captured area.

Type:

sequence of two ints

refresh(buffer=None, format='RGBA')

Refresh video - copy the viewport to an external buffer (optional) then invalidate its current content.

Parameters:

• buffer (any buffer type) – 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.

• format (str) – An optional image format specifier for the image that will be copied to the buffer. Only valid values are “RGBA” or “BGRA”

scale

Fast scale of image (near neighbour).

Type:

bool

size

Image size. (readonly)

Type:

tuple of two ints

valid

Tells if an image is available. (readonly)

Type:

bool

whole

Use whole viewport to capture.

Type:

bool

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

Type:

bool

zbuff

Use depth component of viewport as grey scale color - suitable for texture source.

Type:

bool

Texture classes

class bge.texture.Texture(gameObj, materialID=0, textureID=0, textureObj=None)

Texture object.

Parameters:

• gameObj (KX_GameObject) – Game object to be created a video texture on.

• materialID (int) – Material ID. (optional)

• textureID (int) – Texture ID. (optional)

• textureObj (Texture) – Texture object with shared bindId. (optional)

bindId

OpenGL Bind Name. (readonly)

Type:

int

close()

Close dynamic texture and restore original.

mipmap

Mipmap texture.

Type:

bool

refresh(refresh_source=True, ts=-1.0)

Refresh texture from source.

Parameters:

• refresh_source (bool) – Whether to also refresh the image source of the texture.

• ts (float) – 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 time to it. (optional)

source

Source of texture.

Type:

one of…

• VideoFFmpeg

• ImageFFmpeg

• ImageBuff

• ImageMirror

• ImageMix

• ImageRender

• ImageViewport

Filter classes

class bge.texture.FilterBGR24

Source filter BGR24.

class bge.texture.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.

color

Reference color.

Type:

sequence of three ints

Default:

(0, 0, 255)

limits

Reference color limits.

Type:

sequence of two ints

Default:

(64, 64)

previous

Previous pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

class bge.texture.FilterColor

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.

matrix

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

previous

Previous pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

class bge.texture.FilterGray

Filter for gray scale effect. Proportions of R, G and B contributions in the output gray scale are 28:151:77.

previous

Previous pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

class bge.texture.FilterLevel

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.

levels

Levels matrix [4] (min, max).

Type:

sequence of four sequences of two ints

Default:

((0, 255), (0, 255), (0, 255), (0, 255))

previous

Previous pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

class bge.texture.FilterNormal

Normal map filter.

colorIdx

Index of color used to calculate normal (0 - red, 1 - green, 2 - blue, 3 - alpha).

Type:

int in [0, 3]

Default:

0

depth

Depth of relief.

Type:

float

Default:

4.0

previous

Previous pixel filter.

Type:

one of…

• FilterBGR24

• FilterBlueScreen

• FilterColor

• FilterGray

• FilterLevel

• FilterNormal

• FilterRGB24

• FilterRGBA32

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.

Functions

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:

str

bge.texture.imageToArray(image, mode)

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

Parameters:

• image –

  Image source object of type …

  • VideoFFmpeg

  • ImageFFmpeg

  • ImageBuff

  • ImageMirror

  • ImageMix

  • ImageRender

  • ImageViewport

• mode (str) –

  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 ImageRender objects. The default mode is “RGBA”.

Returns:

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

Return type:

Buffer

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 (KX_GameObject) – The game object that uses the texture you want to make dynamic.

• name (str) – Name of the texture/material you want to make dynamic.

Returns:

The internal material number.

Return type:

int

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 (str) – Name of the error log file.

Returns:

-1 if the parameter name is invalid (not of type string), else 0.

Return type:

int

Constants

FFmpeg Video and Image Status

bge.texture.SOURCE_ERROR

bge.texture.SOURCE_EMPTY

bge.texture.SOURCE_READY

bge.texture.SOURCE_PLAYING

bge.texture.SOURCE_STOPPED

Image Blending Modes

See Wikipedia’s Blend Modes for reference.

bge.texture.IMB_BLEND_MIX

bge.texture.IMB_BLEND_ADD

bge.texture.IMB_BLEND_SUB

bge.texture.IMB_BLEND_MUL

bge.texture.IMB_BLEND_LIGHTEN

bge.texture.IMB_BLEND_DARKEN

bge.texture.IMB_BLEND_ERASE_ALPHA

bge.texture.IMB_BLEND_ADD_ALPHA

bge.texture.IMB_BLEND_OVERLAY

bge.texture.IMB_BLEND_HARDLIGHT

bge.texture.IMB_BLEND_COLORBURN

bge.texture.IMB_BLEND_LINEARBURN

bge.texture.IMB_BLEND_COLORDODGE

bge.texture.IMB_BLEND_SCREEN

bge.texture.IMB_BLEND_SOFTLIGHT

bge.texture.IMB_BLEND_PINLIGHT

bge.texture.IMB_BLEND_VIVIDLIGHT

bge.texture.IMB_BLEND_LINEARLIGHT

bge.texture.IMB_BLEND_DIFFERENCE

bge.texture.IMB_BLEND_EXCLUSION

bge.texture.IMB_BLEND_HUE

bge.texture.IMB_BLEND_SATURATION

bge.texture.IMB_BLEND_LUMINOSITY

bge.texture.IMB_BLEND_COLOR

bge.texture.IMB_BLEND_COPY

bge.texture.IMB_BLEND_COPY_RGB

bge.texture.IMB_BLEND_COPY_ALPHA