bge.logic.setRender(flag) to enable/disable render.
The render pass is enabled by default but it can be disabled with
bge.logic.setRender(False).
Once disabled, the render pass is skipped and a new logic frame starts
immediately. Note that VSync no longer limits the fps when render is off
but the 'Use Frame Rate' option in the Render Properties still does.
To run as many frames as possible, untick the option
This function is useful when you don't need the default render, e.g.
when doing offscreen render to an alternate device than the monitor.
Note that without VSync, you must limit the frame rate by other means.
fbo = bge.render.offScreenCreate(width,height,[,samples=0][,target=bge.render.RAS_OFS_RENDER_BUFFER])
Use this method to create an offscreen buffer of given size, with given MSAA
samples and targetting either a render buffer (bge.render.RAS_OFS_RENDER_BUFFER)
or a texture (bge.render.RAS_OFS_RENDER_TEXTURE). Use the former if you want to
retrieve the frame buffer on the host and the latter if you want to pass the render
to another context (texture are proper OGL object, render buffers aren't)
The object created by this function can only be used as a parameter of the
bge.texture.ImageRender() constructor to send the the render to the FBO rather
than to the frame buffer. This is best suited when you want to create a render
of specific size, or if you need an image with an alpha channel.
bge.texture.<imagetype>.refresh(buffer=None, format="RGBA", ts=-1.0)
Without arg, the refresh method of the image objects is pretty much a no-op, it
simply invalidates the image so that on next texture refresh, the image will
be recalculated.
It is now possible to pass an optional buffer object to transfer the image (and
recalculate it if it was invalid) to an external object. The object must implement
the 'buffer protocol'. The image will be transfered as "RGBA" or "BGRA" pixels
depending on format argument (only those 2 formats are supported) and ts is an
optional timestamp in the image depends on it (e.g. VideoFFmpeg playing a video file).
With this function you don't need anymore to link the image object to a Texture
object to use: the image object is self-sufficient.
bge.texture.ImageRender(scene, camera, fbo=None)
Render to buffer is possible by passing a FBO object (see offScreenCreate).
bge.texture.ImageRender.render()
Allows asynchronous render: call this method to render the scene but without
extracting 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
to which this object is the source. Asynchronous render is useful to achieve 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.
Support negative scale on camera.
Camera scale was previously ignored in the BGE.
It is now injected in the modelview matrix as a vertical or horizontal flip
of the scene (respectively if scaleY<0 and scaleX<0).
Note that the actual value of the scale is not used, only the sign.
This allows to flip the image produced by ImageRender() without any performance
degradation: the flip is integrated in the render itself.
Optimized image transfer from ImageRender to buffer.
Previously, images that were transferred to the host were always going through
buffers in VideoTexture. It is now possible to transfer ImageRender
images to external buffer without intermediate copy (i.e. directly from OGL to buffer)
if the attributes of the ImageRender objects are set as follow:
flip=False, alpha=True, scale=False, depth=False, zbuff=False.
(if you need to flip the image, use camera negative scale)
- Use BGL buffer instead of string for image data.
- Add buffer interface to image source.
- Allow customization of pixel format.
- Add valid property to check if the image data is available.
The image property of all Image source objects will now
return a BGL 'buffer' object. Previously it was returning
a string, which was not working at all with Python 3.1.
The BGL buffer type allows sequence access to bytes and
is directly usable in BGL OpenGL wrapper functions.
The buffer is formated as a 1 dimensional array of bytes
with 4 bytes per pixel in RGBA order.
BGL buffers will also be accepted in the ImageBuff load()
and plot() functions.
It is possible to customize the pixel format by using
the VideoTexture.imageToArray(image, mode) function:
the first argument is a Image source object, the second
optional argument is a format string using the R, G, B,
A, 0 and 1 characters. For example "BGR" means that each
pixel will be 3 bytes, corresponding to the Blue, Green
and Red channel in that order. Use 0 for a fixed hex 00
value, 1 for hex FF. The default mode is "RGBA".
All Image source objects now support the buffer interface
which allows to create memoryview objects for direct access
to the image internal buffer without memory copy. The buffer
format is one dimensional array of bytes with 4 bytes per
pixel in RGBA order. The buffer is writable, which allows
custom modifications of the image data.
v = memoryview(source)
A bug in the Python 3.1 buffer API will cause a crash if
the memoryview object cannot be created. Therefore, you
must always check first that an image data is available
before creating a memoryview object. Use the new valid
attribute for that:
if source.valid:
v = memoryview(source)
...
Note: the BGL buffer object itself does not yet support
the buffer interface.
Note: the valid attribute makes sense only if you use
image source in conjunction with texture object like this:
# refresh texture but keep image data in memory
texture.refresh(False)
if texture.source.valid:
v = memoryview(texture.source)
# process image
...
# invalidate image for next texture refresh
texture.source.refresh()
Limitation: While memoryview objects exist, the image cannot be
resized. Resizing occurs with ImageViewport objects when the
viewport size is changed or with ImageFFmpeg when a new image
is reloaded for example. Any attempt to resize will cause a
runtime error. Delete the memoryview objects is you want to
resize an image source object.
The new class VideoTexture.ImageMirror() is available to perform
automatic mirror rendering.
Constructor:
VideoTexture.ImageMirror(scene,observer,mirror,material)
scene: reference to the scene that will be rendered.
Both observer and mirror must be part of that scene.
observer: reference to a game object used as view point for
mirror rendering: the scene will be rendered through
the mirror as if the active camera was at the observer
location. Usually the observer is the active camera
but you can use any game obejct.
mirror: reference to the mesh object holding the mirror.
material: material ID of the mirror texture as returned by
VideoTexture.materialID(). The mirror is formed by
the polygons mapped to that material.
There are no specific methods or attributes. ImageMirror inherits
all methods and attributes from ImageRender. You must refresh the
parent VideoTexture.Texture object regularly to update the mirror
rendering.
Guidelines on how to create a working mirror:
- Use a texture that is specific to the mirror so that the mirror
rendering only appears on the mirror.
- The mirror must be planar; the algorithm works well only for planar
or quasi planar mirror. For spherical mirror, you will get better
results with ImageRender and a camera at the center of the mirror.
ImageMirror automatically computes the mirror orientation and
position. The mirror doesn't need to be rectangular, it can be
circular or take any form provided it is planar.
- The mirror up direction must be along the Z axis in local mesh
coordinates. If the mirror is not vertical, ImageMirror will
compute the up direction as being the projection of the Z axis
on the mirror plane.
- UV mapping must be set right to get correct mirror rendering:
- make a planar projection of the mirror polygons (Unwrap or projection from view)
- eventually rotate the projection so that UV up direction corresponds to the mesh Z axis
- scale the projection so that the extreme points touch the border of the texture
- flip the UV projection horizontally (scale -1 on X axis). This is needed
because the mirror texture is rendered from the back of the mirror and
thus is reversed from the view point of the observer. Horizontal flip
in the UV map restores the correct orientation.
Besides these simple rules, the mirror rendering is completely automatic.
In particular, you don't need to allocate a camera for the rendering,
ImageMirror creates dynamically a camera for that. The reflection is correct
even on large angles. The mirror can be a dynamic and moving object, the
algorithm always computes the correct camera position based on observer
relative position. You don't have to worry about mirror position in the scene:
the algorithm automatically computes the camera frustum so that any object
behind the mirror is not rendered.
Warnings:
- observer and mirror are references to game objects. ImageMirror keeps
a pointer to them but does not increment the reference count. You must ensure
that these game objects are not deleted as long as you refresh() the ImageMirror
object. You must release the ImageMirror object before you delete the game
objects. To release the ImageMirror object (normally stored in GameLogic),
just assign it to None.
- Mirror rendering is automatically skipped when the observer is behind the mirror
but it is not disabled when the mirror is out of sight of the observer.
You should only refresh the mirror when you know that the observer is likely to see it.
For example, no need to refresh a car inner mirror when the player is not in the car.
Example:
contr = GameLogic.getCurrentController()
# object holding the mirror
mirror = contr.getOwner()
scene = GameLogic.getCurrentScene()
# observer will be the active camere
camera = scene.getObjectList()['OBCamera']
matID = VideoTexture.materialID(mirror, 'IMmirror.png')
GameLogic.mirror = VideoTexture.Texture(mirror, matID)
GameLogic.mirror.source = VideoTexture.ImageMirror(scene,camera,mirror,matID)
# to render the mirror, just call GameLogic.mirror.refresh(True) on each frame.
You can download a demo game (with a video file) here:
http://home.scarlet.be/~tsi46445/blender/VideoTextureDemo.zip
For those who have already downloaded the demo, you can just update the blend file:
http://home.scarlet.be/~tsi46445/blender/MirrorTextureDemo.blend
The only compilation system that works for sure is the MSVC project files. I've tried my best to
update the other compilation system but I count on the community to check and fix them.
This is Zdeno Miklas video texture plugin ported to trunk.
The original plugin API is maintained (can be found here http://home.scarlet.be/~tsi46445/blender/blendVideoTex.html)
EXCEPT for the following:
The module name is changed to VideoTexture (instead of blendVideoTex).
A new (and only) video source is now available: VideoFFmpeg()
You must pass 1 to 4 arguments when you create it (you can use named arguments):
VideoFFmpeg(file) : play a video file
VideoFFmpeg(file, capture, rate, width, height) : start a live video capture
file:
In the first form, file is a video file name, relative to startup directory.
It can also be a URL, FFmpeg will happily stream a video from a network source.
In the second form, file is empty or is a hint for the format of the video capture.
In Windows, file is ignored and should be empty or not specified.
In Linux, ffmpeg supports two types of device: VideoForLinux and DV1394.
The user specifies the type of device with the file parameter:
[<device_type>][:<standard>]
<device_type> : 'v4l' for VideoForLinux, 'dv1394' for DV1394; default to 'v4l'
<standard> : 'pal', 'secam' or 'ntsc', default to 'ntsc'
The driver name is constructed automatically from the device types:
v4l : /dev/video<capture>
dv1394: /dev/dv1394/<capture>
If you have different driver name, you can specify the driver name explicitely
instead of device type. Examples of valid file parameter:
/dev/v4l/video0:pal
/dev/ieee1394/1:ntsc
dv1394:ntsc
v4l:pal
:secam
capture:
Defines the index number of the capture source, starting from 0. The first capture device is always 0.
The VideoTexutre modules knows that you want to start a live video capture when you set this parameter to a number >= 0. Setting this parameter < 0 indicates a video file playback. Default value is -1.
rate:
the capture frame rate, by default 25 frames/sec
width:
height:
Width and height of the video capture in pixel, default value 0.
In Windows you must specify these values and they must fit with the capture device capability.
For example, if you have a webcam that can capture at 160x120, 320x240 or 640x480,
you must specify one of these couple of values or the opening of the video source will fail.
In Linux, default values are provided by the VideoForLinux driver if you don't specify width and height.
Simple example
**************
1. Texture definition script:
import VideoTexture
contr = GameLogic.getCurrentController()
obj = contr.getOwner()
if not hasattr(GameLogic, 'video'):
matID = VideoTexture.materialID(obj, 'MAVideoMat')
GameLogic.video = VideoTexture.Texture(obj, matID)
GameLogic.vidSrc = VideoTexture.VideoFFmpeg('trailer_400p.ogg')
# Streaming is also possible:
#GameLogic.vidSrc = VideoTexture.VideoFFmpeg('http://10.32.1.10/trailer_400p.ogg')
GameLogic.vidSrc.repeat = -1
# If the video dimensions are not a power of 2, scaling must be done before
# sending the texture to the GPU. This is done by default with gluScaleImage()
# but you can also use a faster, but less precise, scaling by setting scale
# to True. Best approach is to convert the video offline and set the dimensions right.
GameLogic.vidSrc.scale = True
# FFmpeg always delivers the video image upside down, so flipping is enabled automatically
#GameLogic.vidSrc.flip = True
if contr.getSensors()[0].isPositive():
GameLogic.video.source = GameLogic.vidSrc
GameLogic.vidSrc.play()
2. Texture refresh script:
obj = GameLogic.getCurrentController().getOwner()
if hasattr(GameLogic, 'video') != 0:
GameLogic.video.refresh(True)
You can download this demo here:
http://home.scarlet.be/~tsi46445/blender/VideoTextureDemo.blendhttp://home.scarlet.be/~tsi46445/blender/trailer_400p.ogg
