blender/source/gameengine/VideoTexture/blendVideoTex.cpp
Benoit Bolsee 149d231d69 VideoTexture: new ImageMirror class for easy mirror (and portal) creation
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
2008-12-04 16:07:46 +00:00

197 lines
5.8 KiB
C++

/* $Id$
-----------------------------------------------------------------------------
This source file is part of VideoTexure library
Copyright (c) 2006 The Zdeno Ash Miklas
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA, or go to
http://www.gnu.org/copyleft/lesser.txt.
-----------------------------------------------------------------------------
*/
#include <PyObjectPlus.h>
#include <RAS_GLExtensionManager.h>
#include <RAS_IPolygonMaterial.h>
//Old API
//#include "TexPlayer.h"
//#include "TexImage.h"
//#include "TexFrameBuff.h"
//#include "TexPlayerGL.h"
#include "ImageBase.h"
#include "FilterBase.h"
#include "Texture.h"
#include "Exception.h"
// get material id
static PyObject * getMaterialID (PyObject *self, PyObject *args)
{
// parameters - game object with video texture
PyObject * obj = NULL;
// material name
char * matName;
// get parameters
if (!PyArg_ParseTuple(args, "Os", &obj, &matName))
return NULL;
// get material id
short matID = getMaterialID(obj, matName);
// if material was not found, report errot
if (matID < 0)
{
PyErr_SetString(PyExc_RuntimeError, "object doesn't have material with given name");
return NULL;
}
// return material ID
return Py_BuildValue("h", matID);
}
// get last error description
static PyObject * getLastError (PyObject *self, PyObject *args)
{
return Py_BuildValue("s", Exception::m_lastError.c_str());
}
// set log file
static PyObject * setLogFile (PyObject *self, PyObject *args)
{
// get parameters
if (!PyArg_ParseTuple(args, "s", &Exception::m_logFile))
return Py_BuildValue("i", -1);
// log file was loaded
return Py_BuildValue("i", 0);
}
// image to numpy array
static PyObject * imageToArray (PyObject * self, PyObject *args)
{
// parameter is Image object
PyObject * pyImg;
if (!PyArg_ParseTuple(args, "O", &pyImg) || !pyImageTypes.in(pyImg->ob_type))
{
// if object is incorect, report error
PyErr_SetString(PyExc_TypeError, "The value must be a image source object");
return NULL;
}
// get image structure
PyImage * img = reinterpret_cast<PyImage*>(pyImg);
// create array object
unsigned int * imgBuff = img->m_image->getImage();
// if image is available, convert it to array
if (imgBuff != NULL)
// Nasty problem here: the image buffer is an array of integers
// in the processor endian format. The user must take care of that in the script.
// Need to find an elegant solution to this problem
return Py_BuildValue("s#", imgBuff, img->m_image->getBuffSize());
// otherwise return None
Py_RETURN_NONE;
}
// metody modulu
static PyMethodDef moduleMethods[] =
{
{"materialID", getMaterialID, METH_VARARGS, "Gets object's Blender Material ID"},
{"getLastError", getLastError, METH_NOARGS, "Gets last error description"},
{"setLogFile", setLogFile, METH_VARARGS, "Sets log file name"},
{"imageToArray", imageToArray, METH_VARARGS, "get array from image source"},
{NULL} /* Sentinel */
};
#if WITH_FFMPEG
extern PyTypeObject VideoFFmpegType;
extern PyTypeObject ImageFFmpegType;
#endif
extern PyTypeObject FilterBlueScreenType;
extern PyTypeObject FilterGrayType;
extern PyTypeObject FilterColorType;
extern PyTypeObject FilterLevelType;
extern PyTypeObject FilterNormalType;
extern PyTypeObject FilterRGB24Type;
extern PyTypeObject FilterRGBA32Type;
extern PyTypeObject FilterBGR24Type;
extern PyTypeObject ImageBuffType;
extern PyTypeObject ImageMixType;
extern PyTypeObject ImageRenderType;
extern PyTypeObject ImageMirrorType;
extern PyTypeObject ImageViewportType;
extern PyTypeObject ImageViewportType;
static void registerAllTypes(void)
{
#if WITH_FFMPEG
pyImageTypes.add(&VideoFFmpegType, "VideoFFmpeg");
pyImageTypes.add(&ImageFFmpegType, "ImageFFmpeg");
#endif
pyImageTypes.add(&ImageBuffType, "ImageBuff");
pyImageTypes.add(&ImageMixType, "ImageMix");
pyImageTypes.add(&ImageRenderType, "ImageRender");
pyImageTypes.add(&ImageMirrorType, "ImageMirror");
pyImageTypes.add(&ImageViewportType, "ImageViewport");
pyFilterTypes.add(&FilterBlueScreenType, "FilterBlueScreen");
pyFilterTypes.add(&FilterGrayType, "FilterGray");
pyFilterTypes.add(&FilterColorType, "FilterColor");
pyFilterTypes.add(&FilterLevelType, "FilterLevel");
pyFilterTypes.add(&FilterNormalType, "FilterNormal");
pyFilterTypes.add(&FilterRGB24Type, "FilterRGB24");
pyFilterTypes.add(&FilterRGBA32Type, "FilterRGBA32");
pyFilterTypes.add(&FilterBGR24Type, "FilterBGR24");
}
PyObject* initVideoTexture(void)
{
// initialize GL extensions
//bgl::InitExtensions(0);
// prepare classes
registerAllTypes();
registerAllExceptions();
if (!pyImageTypes.ready())
return NULL;
if (!pyFilterTypes.ready())
return NULL;
if (PyType_Ready(&TextureType) < 0)
return NULL;
PyObject * m = Py_InitModule4("VideoTexture", moduleMethods,
"Module that allows to play video files on textures in GameBlender.",
(PyObject*)NULL,PYTHON_API_VERSION);
if (m == NULL)
return NULL;
// initialize classes
pyImageTypes.reg(m);
pyFilterTypes.reg(m);
Py_INCREF(&TextureType);
PyModule_AddObject(m, (char*)"Texture", (PyObject*)&TextureType);
// init last error description
Exception::m_lastError[0] = '\0';
return m;
}
// registration to Image types, put here because of silly linker bug