6. External Texture Sources

Introduction

This tutorial will provide a brief introduction of ExternalTextureSource and ExternalTextureSourceManager classes, their relationship, and how the PlugIns work. For those interested in developing a Texture Source Plugin or maybe just wanting to know more about this system, take a look the ffmpegVideoSystem plugin, which you can find more about on the OGRE forums.

What Is An External Texture Source?

How do external texture source plugins benifit OGRE? Well, the main answer is: addding support for any type of texture source does not require changing OGRE to support it... all that is involved is writting a new plugin. Additionally, because the manager uses the StringInterface class to issue commands/params, no change to the material script reader is needs to be made. As a result, if a plugin needs a special parameter set, it just creates a new command in it's Parameter Dictionary. - see ffmpegVideoSystem plugin for an example. To make this work, two classes have been added to OGRE: ExternalTextureSource & ExternalTextureSourceManager.

ExternalTextureSource Class

Default Command Parameters defined in ExternalTextureSource base class are:

• Parameter Name: "filename" Argument Type: Ogre::String Sets a filename plugin will read from
• Parameter Name: "play_mode" Argument Type: Ogre::String Sets initial play mode to be used by the plugin - "play", "loop", "pause"
• Parameter Name: "set_T_P_S" Argument Type: Ogre::String Used to set the technique, pass, and texture unit level to apply this texture to. As an example: To set a technique level of 1, a pass level of 2, and a texture unit level of 3, send this string "1 2 3".
• Parameter Name: "frames_per_second" Argument Type: Ogre::String Set a Frames per second update speed. (Integer Values only)

ExternalTextureSourceManager Class

Note: The function prototypes shown below are mockups - param names are simplified to better illustrate purpose here... Steps needed to create a new texture via ExternalTextureSourceManager:

• Obviously, the first step is to have the desired plugin included in plugin.cfg for it to be loaded.
• Set the desired PlugIn as Active via AdvancedTextureManager::getSingleton().SetCurrentPlugIn( String Type ); -- type is whatever the plugin registers as handling (eg. "video", "flash", "whatever", etc).
• Note: Consult Desired PlugIn to see what params it needs/expects. Set params/value pairs via AdvancedTextureManager::getSingleton().getCurrentPlugIn()->setParameter( String Param, String Value );
• After required params are set, a simple call to AdvancedTextureManager::getSingleton().getCurrentPlugIn()->createDefinedTexture( sMaterialName ); will create a texture to the material name given.

The manager also provides a method for deleting a texture source material: AdvancedTextureManager::DestroyAdvancedTexture( String sTextureName ); The destroy method works by broadcasting the material name to all loaded TextureSourcePlugIns, and the PlugIn who actually created the material is responsible for the deletion, while other PlugIns will just ignore the request. What this means is that you do not need to worry about which PlugIn created the material, or activating the PlugIn yourself. Just call the manager method to remove the material. Also, all texture plugins should handle cleanup when they are shutdown.

Texture Source Material Script

material Example/MyVideoExample
{
	technique
	{
		pass
		{
			texture_unit
			{
				texture_source video
				{
					filename mymovie.mpeg
					play_mode play
					sound_mode on
				}
			}
		}
	}		
}

Simplified Diagram of Process

This diagram uses ffmpegVideoPlugin as example, but all plug ins will work the same in how they are registered/used here. Also note that TextureSource Plugins are loaded/registered before scripts are parsed. This does not mean that they are initialized... Plugins are not initialized until they are set active! This is to ensure that a rendersystem is setup before the plugins might make a call the rendersystem.