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

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

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

## 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`()

    Refresh video - get its status.

    Value: | 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`()

    Refresh image, i.e. load it.

    Value: | 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`()

    Refresh image - invalidate its current content.

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

    Refresh image - invalidate its current content.

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

  Image source from render.

  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.

  `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

  `refresh`()

    Refresh image - invalidate its current content.

  `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

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

    Refresh image - invalidate its current content.

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