Libraries  »  Libs  »  Video  »  TheoraVideoPlugin  »  TheoraVideoPlugin Articles  »  TheoraVideoPlugin HowItWorks

The plugin is organized as a multi-threaded dll, having each video decoded in a separate thread.
Before every GPU frame, OGRE checks with the plugin to see if new frames have been rendered, and if so, transfers pixel information of that frame to a texture.

TheoraVideoClip

This class manages a playing video.

Decode-Blit cycle

When a new TheoraVideoClip is created, it's execute() function runs in a seperate thread, continuously decoding video frames and storing them in memory buffers.
Once time comes for a frame to be displayed, the content of the memory buffer is transfered to a texture holding a frame, and that memory buffer becomes clear for re-usage.
The max number of pre-cached frames can be defined via a material parameter or a call to the TheoraVideoClip instance function.

Frame Caching

Frames are decoded in advance and pixel information is stored in memory RGB buffers. When time comes for the next frame to be displayed, TheoraVideoClip::blitFrameCheck copies that frame buffer to a texture.
The more frames are cached, the smoother the playback.
Why is this necessary? Because some frames take more time to be decoded then others which can be a problem if decoding video frames on demand, as the old plugin did.

YUV to RGB conversion

Theora and many other codecs store pixel information in YUV format, which is better to use for compressing images then RGB. However, our dear textures can only store RGB values, so there is a need for conversion.
Every frame needs to be converted, which obviously eats CPU cycles. The higher the video resolution, the more time it takes each frame.

Currently, you have the choice between two options:

• decode YUV in the plugin, by the CPU. suitable for smaller videos.
• decode YUV on the GPU, via a pixel shader, suitable for larger videos.

 
Depending of your usage scenario, you might favor one method or the other.
If you have only one video running (probably a full-screen cut scene), you might prefer the shader method, but if you use the same video in many locations in your program, you could benefit more from the first method.

TheoraVideoManager

This class handles all TheoraVideoClip instances.

Ogre External Texture Source

The plugin works as an OGRE External texture source plugin, which makes it flexible, and requires less code to work with then if you would use it directly in code.

Video creation

When a new video texture is created, eg. via a material script, OGRE first sets all material options in TheoraVideoManager class via Ogre::ParamCommand class (see eg. CmdOutputMode in VideoManager.cpp for more details).
Then TheoraVideoManager::createDefinedTexture is called by OGRE and a new TheoraVideoClip instance is created.