Texture plug-in

Attention: This module is obsolete. Current version of Bledner contains VideoTexture module created directly from this one.

GameBlender Texture plug-in allows to update textures in GameBlender from various sources (video files, live video from camera devices, static images files or rendered 3d scenes) during gameplay.

This page contains downloads and documentation of actual version of GameBlender Texture plug-in. It requires Blender 2.48 and Python 2.5.x.

License

Plug-in is published under GPL license. It uses parts of Blender codebase, all modified source files from Blender are included in plug-in’s sources.

Plug-in binaries and sources

Plug-in’s binaries for Windows are compiled in VC++ 2008. Binaries contain only VideoDShow class (not VideoOpenCV class) and class ImageRender is currently not available.

Instalation

Windows binaries

First you have to choose, which version of binaries you will use. Then copy file blendVideoTex.pyd to folder, that is included in PYTHONPATH environment variable. That’s the safe way.

Other options to store plug-in binaries:

• folder, where Blender is installed
• folder, where your .blend file is stored

Plug-in’s API

Plug-in API contains 3 kinds of classes:

• Texture class manages texture content – loads images into texture, saves and restores original texture.
• Image classes provide images for Texture class from various sources. Special kind of Image classes are Video classes, they allow to access video files and camera devices. Every object of Texture class uses as a source one object of Image classes.
• Filter classes allow to convert image formats and to modify image content. Filter objects perform pixel filtering and can be chained together to combine their effects. Any object of Image classes can use one chain of Filter objects. Every pixel of image is processed by all filters in chain serially.

Plug-in module functions:

• materialID (object, matName) – returns material number for specified game object and material name. Parameters: object is a game object, matName is name of material. If material with given name is not found, exception is thrown.
• setLogFile (fileName) – sets log file to write log messages.
• getLastError () – returns text of the last error message.
• imageToArray (image) – converts image data from Image object to python array object (module numpy). Array object is used for image representation in PyARTK (ARToolKit python wrapper).

Texture class

Texture class manages texture content. Its members are:

• Texture (object, materialID, textureID, textureObj) – constructor of texture object. Parameters:
  object is a game object,
  materialID is index of object’s material (default is 0),
  textureID is index of texture in material (default is 0),
  textureObj is another texture object (default is None), that will share the same texture with constructed object. This is usable, when the same texture has to be applied on more than one material. Then only one Texture object can be refreshed and all other objects sharing the same texture will be refreshed too.
• refresh (refreshSource) – load image from source to texture, if image is available. If image sizes aren’t power of 2 values, image is scaled to fulfill this requirement. Parameter refreshSource is bool, it specifies, if image source has to be refreshed after texture is loaded.
• close () – restores original texture.
• source – image object, that provides data for loading to texture.
• mipmap – bool value, that allows mipmap generation for loaded texture.

Image classes

Common members of all Image classes – these functions and attributes are available in every object of Image classes:

• refresh() – invalidates current image data (allows to load new image data).
• image – provides read-only access to image data. Data are in internal format RGBA (4 bytes, red is first/lowest byte, alpha is last/highest byte) and are presented as a python string.
• size – read-only size of image as sequence [width, height].
• scale – if true and resize is needed, then image is resized in Image object using fast algorithm (near neighbour).
• flip – if true, flips image vertically.
• filter – last filter in filter chain.

Filter classes

Common member of all Filter classes:

• previous – previous filter in filter chain. Filter chain is built and managed from its tail, last filter (stored in Image object) contains recursively all its previous filters.

Video classes

Common members of all Video classes – these functions and attributes are available in every object of Video classes:

• play() – starts replay of video file or capture of camera device.
• stop() – stops (pauses) replay of video file or capture of camera device.
• refresh() – invalidates current video frame, allows to load next video frame and returns video status.
• status – provides read-only status of video replay:
  0 – empty,
  1 – ready to play,
  2 – playing,
  3 – stopped,
  -1 – error.
• range – sequence of two float numbers that specify start and end time of replayed video in seconds.
• repeat – repeat count, -1 for infinite repeat
• framerate – float number specifies relative frame rate of video. Examples:
  1.0 – normal speed,
  0.5 – half speed replay,
  2.0 – double speed replay.

VideoDShow class

VideoDShow class uses DirectShow to access video files or camera devices. It’s usable only on Windows OS, but have some advantages (slightly better performance, extended properties for cameras).

Constructor VideoDShow(fileName, captureID, width, height) – creates object of VideoDShow class and sets its basic properties. It allows to use various video frame formats, correct format is identified during initialization automatically. Currently supported formats are RGB24 and YV12.

Constructor’s parameters:

• fileName is name (and path) of video file, if name ‘cam’ is specified, camera device will be used.
• captureID is index of camera device (used only if fileName == ‘cam’). If not provided, first camera device will be used (captureID = 0).
• width and height are suggested sizes of captured images from camera devices (used only if fileName == ‘cam’). If not provided, default sizes of camera device are used.

VideoDShow class contains all common members of Image and Video classes.VideoOpenCV class

VideoOpenCV class uses OpenCV library to access video files or camera devices. It’s a multiplatform library usable on Windows, Linux and MacOS.

Constructor VideoOpenCV(fileName, captureID, useThread) – creates object of VideoOpenCV class. Constructor’s parameters:

• fileName is name (and path) of video file, if name ‘cam’ is specified, camera device will be used.
• captureID is index of camera device (used only if fileName == ‘cam’). If not provided, first camera device will be used (captureID = 0).
• useThread is bool (default is true) that suggests to process video frames in separate thread.

VideoOpenCV class contains all common members of Image and Video classes.

ImageBuff class

ImageBuff class represents source of image data provided in a buffer (string). This class allows to load to texture any kind of image available in Python. For example images in Python Image Library (PIL) can be converted by method tostring() to become loadable to object of ImageBuff class. If ImageBuff object has no filter, object of FilterBGR24 class is used as default filter (works correctly with PIL images).

ImageBuff class has all common members of Image classes except function refresh(). Special members of this class are:

• ImageBuff() – constructor creates object of ImageBuff class.
• load(imageData, width, height) – loads image data to object. Data has to be in supported format (currently RGB24 or BGR24, default is BGR24).

ImageViewport class

ImageViewport class allows to use viewport content as texture – texture then contains copy of current OpenGL framebuffer. Class works in two modes:

1. Direct copy of viewport part with sizes equal to power of 2 values. This mode uses only part of whole viewport, but it can be copied directly to texture with very low overhead. There are additional requirements for this mode – no filter ucan be used and ImageViewport object must be directly used in Texture object. Otherwise is copy to image buffer performed (the same as in the second mode).
2. Copy of whole viewport. This mode copies whole viewport content to image buffer – data are transfered from graphic card to main memory.

ImageViewport class has all common members of Image classes. Special members of this class are:

• ImageViewport () – constructor creates object of ImageViewport class.
• whole – bool that specifies, if whole viewport is used
• position – sequence of two integers specifies position of upper left corner of used area in viewport (if whole is false).

ImageRender class

ImageRender class provides “render to texture” feature. It renders specified scene from specified camera and result of render loads into texture. Class works in two modes similar to modes of ImageViewport class, but rendering area sizes are always power of 2 values:

1. Direct copy of render to texture is performed, if there is no filter used and ImageRender object is directly used in Texture object.
2. Copy to image buffer in main memory is performed otherwise.

ImageRender class has all common members of Image classes. Special members of this class are:

• ImageRender (scene, camera) – constructor creates object of ImageRender class. Parameters:
  scene – scene object, that has to be rendered,
  camera – camera object used to render scene.
• background – sequence of three integers specifies color of background in rendered scene. This can be set independently from background color in standard render.

ImageMix class

ImageMix class is special kind of Image class. It uses other Image objects as sources of images and merges them together to result image. Every image source is weighted. Sum of all weights has to be <= 256 (otherwise color artefacts may appear). All source images must have the same sizes. Objects of this class can be used to mix various image sources, create dynamic interleavings…

ImageMix class has all common members of Image classes. Special members of this class are:

• getSource (id) – returns image object that is identified by string id. If image object is not found, None is returned.
• setSource (id, imageObj) – stores image object identified by string id. If there already was any image object stored with the same id, it’s replaced by new object. If imageObj is None, source identified by id is removed.
• getWeight (id) – returns integer weight of source identified by string id. If id isn’t found, 0 is returned.
• setWeight (id, weight) – sets integer weight of source identified by string id. If id isn’t found, exception is thrown.

FilterRBG24 and FilterBGR24 classes

These classes are designed to convert 3-byte RGB formats to internal RGBA format. They don\’t have attribute previous, because they have to be on the first position in filter chain. Their main use is in class ImageBuff to convert images from source formats. Internally they are used in Video classes, too.

FilterRGB24 class converts 3-byte RGB format, where red is in the first byte, green in the second, and blue in the third.FilterBGR24 class converts 3-byte RGB format, where blue is in the first byte, green in the second, and red in the third.

FilterGray class

FilterGray is simple filter that converts source image to gray-scale. It have common attributes of Filter classes only.

FilterColor class

FilterColor provides general color transformation filter. Resulting color values are calculated using matrix 4×5. Every matrix row contains parameters for one color channel calculation (order of rows: red, green, blue, alpha), and parameters in row define koeficients for source color channels (in order: red, green, blue, alpha, constant). Resulting colors aren’t checked for color value limits, so parameters should be set carefully to avoid artifacts.

FilterColor class has common attributes of Filter classes. Special member of this class is:

• matrix – 4×5 integer matrix that contains parameters for color calculation.

FilterNormal class

FilterNormal class generates normal map from source image. It uses one of color channels as height map and calculates normals from it.

FilterNormal class has common attributes of Filter classes. Special members of this class are:

• colorIdx – index of color channel (red = 0, green = 1, blue = 2)
• depth – depth of height map (distance between minimal and maximal height in pixel units). Default value is 4.

FilterBlueScreen class

FilterBlueScreen class generates alpha value from source colors. It allows to set color that is considered as “blue screen color” and for this color and color similar to it will make pixels transparent, for other colors it will be opaque. Similarity of colors is calculated as sum of squared color channel differences from “blue screen” color.

FilterBlueScreen class has common attributes of Filter classes. Special members of this class are:

• color – sequence of three integer values that represents color values for “blue screen” color (order: red, green, blue).
• limits – sequence of two integers that defines limits of color differences.
  If difference is <= limits[0], pixel is fully transparent.
  If difference is >= limits[1], pixel is fully opaque.
  If difference is between limits[0] and limits[1], pixel will be semi-transparent – calculated by linear function of difference value.