moglmorpher_16texunits_slow

Psychtoolbox › PsychOpenGL

Matlab OpenGL Morpher - Performs linear morphs between different 3D shapes and
renders the resulting shape via OpenGL. Supports high-performance GPU
based morphing on recent graphics hardware.

The moglmorpher computes linear combinations of shapes and their corresponding
surface normal vectors and texture coordinate assignments. It then renders the
resulting shape with its resulting surface normals and texture coordinates in
an efficient way, using the OpenGL for Matlab (MOGL) functions.

It also allows to render single sub-meshes efficiently, as well as
predictions of screen space 2D (x,y) coordinates of vertices in the mesh.

The whole setup for rendering (rigid orientation and position, camera view transforms,
assignment and setup of textures or material properties, lighting, shaders, ...) is
left to the calling parent routines, focusing solely on high performance morphing
and rendering of generic triangle meshes. This allows for maximum flexibility.

For a specific example of usage, have a look at MorphDemo.m

IMPORTANT: At the end of your script, you must call moglmorpher('reset')
to release all ressources and reset moglmorpher into a well-defined
state. Alternatively, you can call 'clear moglmorpher', e.g., if your
script aborted with an error. If your forget either of these, you'll see
some weird error messages about "Invalid window record referenced"
at invocation of the command.

Available subcommands and their meaning

moglmorpher('ForceGPUMorphingEnabled', enableflag);

Forcefully enable or disable GPU based morphing. 'enableFlag'==1 ->
Forcefully enable, 'enableFlag'==0 --> Forcefully disable.

moglmorpher can perform all morphing computations and rendering completely
on the GPU on modern graphics hardware that supports this. This provides
a significant speedup over morphing in Matlab/Octave code on the slower
CPU. Normally, moglmorpher auto-detects if GPU based morphing is possible
and then enables that feature. If GPU morphing is not possible, it
reverts to a slower Matlab CPU implementation of morphing. For GPU
morphing, the Psychtoolbox imaging pipeline needs to be enabled by
passing an optional valid non-zero 'imagingMode' flag to the
Screen('OpenWindow', ...); call when opening the onscreen window. E.g.,
the flag 'kPsychNeedFastOffscreenWindows' would enable the pipeline.

There may be cases where either auto-detection goes wrong, or where you
don't want to use GPU based morphing, e.g., if your hardware/gfx-driver
is defective and GPU morphing doesn't work correctly, or if you want to
use the moglmorpher('renderNormals') subfunction which is not yet
supported in GPU mode, or if you want to perform benchmarking of GPU vs.
non-GPU mode. In such cases you can use this subfunction to manually
enable/disable GPU based morphing, overriding the auto-detection code.

It's important to call this function before the first invocation of any
other subfunction!

GPU based operation should be efficiently supported on all ATI Radeon
X-1000 or later hardware and all NVidia Geforce-6000 and later hardware.



All following subfunctions must be only called when at least one onscreen
window is open!

meshid = moglmorpher('addMesh', obj);
-- Add a new shape to the collection of shapes to be morphed. 'obj'
is a single struct that defines the object: Subfields are obj.faces,
obj.vertices, obj.texcoords, obj.normals. Their meaning is the same as
the corresponding parameters in the following 'addMesh' subcommand. The
'obj' syntax is provided for convenience, as 'obj' in the same format as
provided by LoadOBJFile, i.e. obj = LoadOBJFile('myfile.obj') will load
the geometry in 'myfile.obj' into obj, which can then be passed to
moglmorpher via moglmorpher('addMesh', obj{1}); to add the first mesh
from 'myfile.obj' into the morpher.

meshid = moglmorpher('addMesh', faces, vertices [, texcoords] [, normals]);
-- Add a new shape to the collection of shapes to be morphed. faces == Index
list that defines the topology of the shape: faces is a 3 by n vector. Each of
the n columns defines one 3D triangle face, the 3 indices in the column are
indices into the vertices, texcoords and normals vectors that define the
properties of the vertices.

vertices == A 3-by-m vector that defines the shape of the object: Each of the
m columns defines the 3D position of one of the corresponding m vertices.

normals == A 3-by-m vector whose single columns define the (nx,ny,nz) components
of unit normal surface vectors. The normals vector is optional and only needed if
you want to do proper lighting calculations on your object.

texcoords == A 2-by-m vector of 2D texture coordinates for each corresponding vertex.
This vector is optional and only needed if you want to apply textures to the object.

The size and dimension of all provided vectors must match (==be identical) for all
shapes. This is required, because otherwise the linear combination of shapes and
normal vectors wouldn't be mathematically well defined.

The function call returns a handle (a unique numeric id) for the mesh.

moglmorpher('renderMesh', meshid);
-- Render the mesh corresponding to the handle 'meshid'.

moglmorpher('renderMorph', weights [,morphnormals=1]);
-- Compute a linear combination (a weighted average) of all stored meshes, as defined
by the vector 'weights'. Render the final shape.
For 'count' shapes, weight is a vector of length 'count'. The i'th scalar entry of weight
is the coefficient used to integrate the i'th shape into the morph.

moglmorpher('computeMorph', weights [,morphnormals=1]);
-- Same as 'renderMorph', just that rendering of the morphed shape is
omitted. You can render the shape later by calling the 'render' subcommand.

finalresult = sum_for_i=1_to_count(shape(i) * weights(i));
The shape (vertices) and normal vectors are linearly combined. The texture coordinates are
not altered by the morph. If you set the optional argument morphnormals to zero, then
normals are not touched by morphing either.

moglmorpher('render');
-- Renders the last shape again. This is either the last rendered mesh or the last linear
combination.

glListHandle = moglmorpher('renderToDisplaylist');
-- Same as subcommand 'render', but the shape is not rendered as an image to the
framebuffer, but stored to a new OpenGL display list. A unique 'glListHandle' to
the new list is returned. Using this handle one can render the object
later on via the command glCallList(glListHandle); and delete it via
glDeleteLists(glListHandle, 1);

moglmorpher('renderNormals' [,normalLength=1]);
-- Renders the surface normal vectors of the last shape in green, either at unit-length,
or at 'normalLength' if this argument is provided. This is a helper function for
checking the correctness of computed normals. It is very slow!

vpos = moglmorpher('getVertexPositions', windowPtr [, startidx=1] [, endidx]);
-- Compute and return a matrix which contains the projected screen space coordinates of all
vertices that would be rendered when calling moglmorpher('render'). windowPtr is the handle
of the window into which we render. Optional arguments startidx and endidx define the
index of the first vertex, resp. the last vertex to transform. The returned 'vpos' is a
vcount-by-3 matrix, where vcount is the number of returned vertices, and row i contains the
projected 3D position of the i'th vertex vcount(i,:) = (screen_x, screen_y, depth_z);

count = moglmorpher('getMeshCount');
Returns number of stored shapes.

moglmorpher('reset');
Resets the moglmorpher - deletes all internal data structures.