
\begin{DoxyItemize}
\item \hyperlink{Introduction}{Introduction}
\item \hyperlink{The-Core-Objects}{The Core Objects}
\item \hyperlink{Scripts}{Scripts}
\item \hyperlink{High-level-Programs}{High-\/level Programs}
\item \hyperlink{Runtime-Shader-Generation}{Runtime Shader Generation}
\item \hyperlink{Mesh-Tools}{Mesh Tools}
\item \hyperlink{Hardware-Buffers}{Hardware Buffers}
\item \hyperlink{Shadows}{Shadows}
\item \hyperlink{Animation}{Animation} 
\end{DoxyItemize}\hypertarget{Introduction}{}\section{Introduction}\label{Introduction}
This chapter is intended to give you an overview of the main components of O\+G\+RE and why they have been put together that way.

\section*{Object Orientation -\/ more than just a buzzword}

The name is a dead giveaway. It says Object-\/\+Oriented Graphics Rendering Engine, and that’s exactly what it is. Ok, but why? Why did I choose to make such a big deal about this?

Well, nowadays graphics engines are like any other large software system. They start small, but soon they balloon into monstrously complex beasts which just can’t be all understood at once. It’s pretty hard to manage systems of this size, and even harder to make changes to them reliably, and that’s pretty important in a field where new techniques and approaches seem to appear every other week. Designing systems around huge files full of C function calls just doesn’t cut it anymore -\/ even if the whole thing is written by one person (not likely) they will find it hard to locate that elusive bit of code after a few months and even harder to work out how it all fits together.

Object orientation is a very popular approach to addressing the complexity problem. It’s a step up from decomposing your code into separate functions, it groups function and state data together in classes which are designed to represent real concepts. It allows you to hide complexity inside easily recognised packages with a conceptually simple interface so they are easy to recognise and have a feel of ’building blocks’ which you can plug together again later. You can also organise these blocks so that some of them look the same on the outside, but have very different ways of achieving their objectives on the inside, again reducing the complexity for the developers because they only have to learn one interface.

I’m not going to teach you OO here, that’s a subject for many other books, but suffice to say I’d seen enough benefits of OO in business systems that I was surprised most graphics code seemed to be written in C function style. I was interested to see whether I could apply my design experience in other types of software to an area which has long held a place in my heart -\/ 3D graphics engines. Some people I spoke to were of the opinion that using full C++ wouldn’t be fast enough for a real-\/time graphics engine, but others (including me) were of the opinion that, with care, and object-\/oriented framework can be performant. We were right.

In summary, here’s the benefits an object-\/oriented approach brings to O\+G\+RE\+:


\begin{DoxyDescription}
\item[Abstraction ]

Common interfaces hide the nuances between different implementations of 3D A\+PI and operating systems


\item[Encapsulation ]

There is a lot of state management and context-\/specific actions to be done in a graphics engine -\/ encapsulation allows me to put the code and data nearest to where it is used which makes the code cleaner and easier to understand, and more reliable because duplication is avoided


\item[Polymorphism ]

The behaviour of methods changes depending on the type of object you are using, even if you only learn one interface, e.\+g. a class specialised for managing indoor levels behaves completely differently from the standard scene manager, but looks identical to other classes in the system and has the same methods called on it


\end{DoxyDescription}

\label{_Multi_002deverything}%
 \label{_Multi_002deverything-1}%


\section*{Multi-\/everything}

I wanted to do more than create a 3D engine that ran on one 3D A\+PI, on one platform, with one type of scene (indoor levels are most popular). I wanted O\+G\+RE to be able to extend to any kind of scene (but yet still implement scene-\/specific optimisations under the surface), any platform and any 3D A\+PI.

Therefore all the ’visible’ parts of O\+G\+RE are completely independent of platform, 3D A\+PI and scene type. There are no dependencies on Windows types, no assumptions about the type of scene you are creating, and the principles of the 3D aspects are based on core maths texts rather than one particular A\+PI implementation.

Now of course somewhere O\+G\+RE has to get down to the nitty-\/gritty of the specifics of the platform, A\+PI and scene, but it does this in subclasses specially designed for the environment in question, but which still expose the same interface as the abstract versions.

For example, there is a ’\+Win32\+Window’ class which handles all the details about rendering windows on a Win32 platform -\/ however the application designer only has to manipulate it via the superclass interface ’\+Render\+Window’, which will be the same across all platforms.

Similarly the ’\+Scene\+Manager’ class looks after the arrangement of objects in the scene and their rendering sequence. Applications only have to use this interface, but there is a ’\+Bsp\+Scene\+Manager’ class which optimises the scene management for indoor levels, meaning you get both performance and an easy to learn interface. All applications have to do is hint about the kind of scene they will be creating and let O\+G\+RE choose the most appropriate implementation -\/ this is covered in a later tutorial.

O\+G\+R\+E’s object-\/oriented nature makes all this possible. Currently O\+G\+RE runs on Windows, Linux and Mac O\+SX using plugins to drive the underlying rendering A\+PI (currently Direct3D or Open\+GL). Applications use O\+G\+RE at the abstract level, thus ensuring that they automatically operate on all platforms and rendering subsystems that O\+G\+RE provides without any need for platform or A\+PI specific code. \hypertarget{The-Core-Objects}{}\section{The Core Objects}\label{The-Core-Objects}
This tutorial gives you a quick summary of the core objects that you will use in O\+G\+RE and what they are used for.

\label{_A-Word-About-Namespaces}%


\section*{A Word About Namespaces}

O\+G\+RE uses a C++ feature called namespaces. This lets you put classes, enums, structures, anything really within a ’namespace’ scope which is an easy way to prevent name clashes, i.\+e. situations where you have 2 things called the same thing. Since O\+G\+RE is designed to be used inside other applications, I wanted to be sure that name clashes would not be a problem. Some people prefix their classes/types with a short code because some compilers don’t support namespaces, but I chose to use them because they are the ’right’ way to do it. Sorry if you have a non-\/compliant compiler, but hey, the C++ standard has been defined for years, so compiler writers really have no excuse anymore. If your compiler doesn’t support namespaces then it’s probably because it’s sh$\ast$t -\/ get a better one. ;)

This means every class, type etc should be prefixed with \hyperlink{namespace_ogre}{Ogre}, e.\+g. \hyperlink{class_ogre_1_1_camera}{Ogre\+::\+Camera}, \hyperlink{class_ogre_1_1_vector3}{Ogre\+::\+Vector3} etc which means if elsewhere in your application you have used a Vector3 type you won’t get name clashes. To avoid lots of extra typing you can add a ’using namespace \hyperlink{namespace_ogre}{Ogre};’ statement to your code which means you don’t have to type the \hyperlink{namespace_ogre}{Ogre} prefix unless there is ambiguity (in the situation where you have another definition with the same name).

\label{_Overview-from-10_002c000-feet}%


\section*{Overview from 10,000 feet}

Shown below is a diagram of some of the core objects and where they ’sit’ in the grand scheme of things. This is not all the classes by a long shot, just a few examples of the more more significant ones to give you an idea of how it slots together. 

At the very top of the diagram is the Root object. This is your ’way in’ to the O\+G\+RE system, and it’s where you tend to create the top-\/level objects that you need to deal with, like scene managers, rendering systems and render windows, loading plugins, all the fundamental stuff. If you don’t know where to start, Root is it for almost everything, although often it will just give you another object which will actually do the detail work, since Root itself is more of an organiser and facilitator object.

The majority of rest of O\+G\+R\+E’s classes fall into one of 3 roles\+:


\begin{DoxyDescription}
\item[Scene Management ]

This is about the contents of your scene, how it’s structured, how it’s viewed from cameras, etc. Objects in this area are responsible for giving you a natural declarative interface to the world you’re building; i.\+e. you don’t tell O\+G\+RE \char`\"{}set these render states and then render 3 polygons\char`\"{}, you tell it \char`\"{}\+I want an object here, here and here, with these materials on them, rendered from this view\char`\"{}, and let it get on with it.


\item[Resource Management ]

All rendering needs resources, whether it’s geometry, textures, fonts, whatever. It’s important to manage the loading, re-\/use and unloading of these things carefully, so that’s what classes in this area do.


\item[Rendering ]

Finally, there’s getting the visuals on the screen -\/ this is about the lower-\/level end of the rendering pipeline, the specific rendering system A\+PI objects like buffers, render states and the like and pushing it all down the pipeline. Classes in the Scene Management subsystem use this to get their higher-\/level scene information onto the screen.


\end{DoxyDescription}

You’ll notice that scattered around the edge are a number of plugins. O\+G\+RE is designed to be extended, and plugins are the usual way to go about it. Many of the classes in O\+G\+RE can be subclassed and extended, whether it’s changing the scene organisation through a custom Scene\+Manager, adding a new render system implementation (e.\+g. Direct3D or Open\+GL), or providing a way to load resources from another source (say from a web location or a database). Again this is just a small smattering of the kinds of things plugins can do, but as you can see they can plug in to almost any aspect of the system. This way, O\+G\+RE isn’t just a solution for one narrowly defined problem, it can extend to pretty much anything you need it to do.\hypertarget{_the-_core-_objects_The-Root-Object}{}\subsection{The Root object}\label{_the-_core-_objects_The-Root-Object}
The \hyperlink{class_ogre_1_1_root}{Ogre\+::\+Root} object is the entry point to the O\+G\+RE system. This object M\+U\+ST be the first one to be created, and the last one to be destroyed. In the example applications I chose to make an instance of Root a member of my application object which ensured that it was created as soon as my application object was, and deleted when the application object was deleted.

The root object lets you configure the system, for example through the \hyperlink{class_ogre_1_1_root_aedc76ef3bdc6514bd4655be0d70d6bcd}{Ogre\+::\+Root\+::show\+Config\+Dialog} method which is an extremely handy method which performs all render system options detection and shows a dialog for the user to customise resolution, colour depth, full screen options etc. It also sets the options the user selects so that you can initialise the system directly afterwards.

The root object is also your method for obtaining pointers to other objects in the system, such as the \hyperlink{class_ogre_1_1_scene_manager}{Ogre\+::\+Scene\+Manager}, \hyperlink{class_ogre_1_1_render_system}{Ogre\+::\+Render\+System} and various other resource managers. See below for details.

Finally, if you run O\+G\+RE in continuous rendering mode, i.\+e. you want to always refresh all the rendering targets as fast as possible (the norm for games and demos, but not for windowed utilities), the root object has a method called \hyperlink{class_ogre_1_1_root_a8eda253befda1255cbfd3b298f62449e}{Ogre\+::\+Root\+::start\+Rendering}, which when called will enter a continuous rendering loop which will only end when all rendering windows are closed, or any \hyperlink{class_ogre_1_1_frame_listener}{Ogre\+::\+Frame\+Listener} objects indicate that they want to stop the cycle (see below for details of \hyperlink{class_ogre_1_1_frame_listener}{Ogre\+::\+Frame\+Listener} objects).\hypertarget{_the-_core-_objects_The-RenderSystem-object}{}\subsection{The Render\+System object}\label{_the-_core-_objects_The-RenderSystem-object}
The \hyperlink{class_ogre_1_1_render_system}{Ogre\+::\+Render\+System} object is actually an abstract class which defines the interface to the underlying 3D A\+PI. It is responsible for sending rendering operations to the A\+PI and setting all the various rendering options. This class is abstract because all the implementation is rendering A\+PI specific -\/ there are A\+P\+I-\/specific subclasses for each rendering A\+PI (e.\+g. D3\+D\+Render\+System for Direct3D). After the system has been initialised through \hyperlink{class_ogre_1_1_root_a6ab8f204bbfb150ad180eb6e78e4639c}{Ogre\+::\+Root\+::initialise}, the \hyperlink{class_ogre_1_1_render_system}{Ogre\+::\+Render\+System} object for the selected rendering A\+PI is available via the \hyperlink{class_ogre_1_1_root_ab8ca3d5abebba7a14650db5f618286d0}{Ogre\+::\+Root\+::get\+Render\+System()} method.

However, a typical application should not normally need to manipulate the \hyperlink{class_ogre_1_1_render_system}{Ogre\+::\+Render\+System} object directly -\/ everything you need for rendering objects and customising settings should be available on the \hyperlink{class_ogre_1_1_scene_manager}{Ogre\+::\+Scene\+Manager}, Material and other scene-\/oriented classes. It’s only if you want to create multiple rendering windows (completely separate windows in this case, not multiple viewports like a split-\/screen effect which is done via the Render\+Window class) or access other advanced features that you need access to the Render\+System object.

For this reason I will not discuss the \hyperlink{class_ogre_1_1_render_system}{Ogre\+::\+Render\+System} object further in these tutorials. You can assume the \hyperlink{class_ogre_1_1_scene_manager}{Ogre\+::\+Scene\+Manager} handles the calls to the \hyperlink{class_ogre_1_1_render_system}{Ogre\+::\+Render\+System} at the appropriate times.\hypertarget{_the-_core-_objects_The-SceneManager-object}{}\subsection{The Scene\+Manager object}\label{_the-_core-_objects_The-SceneManager-object}
Apart from the \hyperlink{class_ogre_1_1_root}{Ogre\+::\+Root} object, this is probably the most critical part of the system from the application’s point of view. Certainly it will be the object which is most used by the application. The \hyperlink{class_ogre_1_1_scene_manager}{Ogre\+::\+Scene\+Manager} is in charge of the contents of the scene which is to be rendered by the engine. It is responsible for organising the contents using whatever technique it deems best, for creating and managing all the cameras, movable objects (entities), lights and materials (surface properties of objects), and for managing the ’world geometry’ which is the sprawling static geometry usually used to represent the immovable parts of a scene.

It is to the Scene\+Manager that you go when you want to create a camera for the scene. It’s also where you go to retrieve or to remove a light from the scene. There is no need for your application to keep lists of objects, the Scene\+Manager keeps a named set of all of the scene objects for you to access, should you need them. Look in the main documentation under the get\+Camera, get\+Light, get\+Entity etc methods.

The Scene\+Manager also sends the scene to the Render\+System object when it is time to render the scene. You never have to call the \hyperlink{class_ogre_1_1_scene_manager_a29ba8a2cad151d307d04781f749e7e84}{Ogre\+::\+Scene\+Manager\+::\+\_\+render\+Scene} method directly though -\/ it is called automatically whenever a rendering target is asked to update.

So most of your interaction with the Scene\+Manager is during scene setup. You’re likely to call a great number of methods (perhaps driven by some input file containing the scene data) in order to set up your scene. You can also modify the contents of the scene dynamically during the rendering cycle if you create your own Frame\+Listener object (see later).

Because different scene types require very different algorithmic approaches to deciding which objects get sent to the Render\+System in order to attain good rendering performance, the Scene\+Manager class is designed to be subclassed for different scene types. The default Scene\+Manager object will render a scene, but it does little or no scene organisation and you should not expect the results to be high performance in the case of large scenes. The intention is that specialisations will be created for each type of scene such that under the surface the subclass will optimise the scene organisation for best performance given assumptions which can be made for that scene type. An example is the Bsp\+Scene\+Manager which optimises rendering for large indoor levels based on a Binary Space Partition (B\+SP) tree.

The application using O\+G\+RE does not have to know which subclasses are available. The application simply calls \hyperlink{class_ogre_1_1_root_a8bb8655f823a98007775f69278c1b0f9}{Ogre\+::\+Root\+::create\+Scene\+Manager}(..) passing as a parameter one of a number of scene types (e.\+g. \hyperlink{group___scene_gga7383602bd480d43b80c626969b9af914a0af8f844019e52fe112e9a946a919fcd}{Ogre\+::\+S\+T\+\_\+\+G\+E\+N\+E\+R\+IC}, \hyperlink{group___scene_gga7383602bd480d43b80c626969b9af914a93f2170ad3a8132f29264dc3642a2dcf}{Ogre\+::\+S\+T\+\_\+\+I\+N\+T\+E\+R\+I\+OR} etc). O\+G\+RE will automatically use the best Scene\+Manager subclass available for that scene type, or default to the basic Scene\+Manager if a specialist one is not available. This allows the developers of O\+G\+RE to add new scene specialisations later and thus optimise previously unoptimised scene types without the user applications having to change any code.\hypertarget{_the-_core-_objects_The-ResourceGroupManager-Object}{}\subsection{The Resource\+Group\+Manager Object}\label{_the-_core-_objects_The-ResourceGroupManager-Object}
The \hyperlink{class_ogre_1_1_resource_group_manager}{Ogre\+::\+Resource\+Group\+Manager} class is actually a ’hub’ for loading of reusable resources like textures and meshes. It is the place that you define groups for your resources, so they may be unloaded and reloaded when you want. Servicing it are a number of Resource\+Managers which manage the individual types of resource, like \hyperlink{class_ogre_1_1_texture_manager}{Ogre\+::\+Texture\+Manager} or \hyperlink{class_ogre_1_1_mesh_manager}{Ogre\+::\+Mesh\+Manager}. In this context, resources are sets of data which must be loaded from somewhere to provide O\+G\+RE with the data it needs.

Resource\+Managers ensure that resources are only loaded once and shared throughout the O\+G\+RE engine. They also manage the memory requirements of the resources they look after. They can also search in a number of locations for the resources they need, including multiple search paths and compressed archives (Z\+IP files).

Most of the time you won’t interact with resource managers directly. Resource managers will be called by other parts of the O\+G\+RE system as required, for example when you request for a texture to be added to a Material, the \hyperlink{class_ogre_1_1_texture_manager}{Ogre\+::\+Texture\+Manager} will be called for you. If you like, you can call the appropriate resource manager directly to preload resources (if for example you want to prevent disk access later on) but most of the time it’s ok to let O\+G\+RE decide when to do it.

One thing you will want to do is to tell the resource managers where to look for resources. You do this via Root\+::get\+Singleton().add\+Resource\+Location, which actually passes the information on to \hyperlink{class_ogre_1_1_resource_group_manager}{Ogre\+::\+Resource\+Group\+Manager}.

Because there is only ever 1 instance of each resource manager in the engine, if you do want to get a reference to a resource manager use the following syntax\+:


\begin{DoxyCode}
\hyperlink{class_ogre_1_1_texture_manager_ac6fb858ee86f3b7b75de32e3e04ee5c8}{Ogre::TextureManager::getSingleton}().someMethod()
\hyperlink{class_ogre_1_1_mesh_manager_a2efefa307b7987c5fcff7e8c47f79758}{Ogre::MeshManager::getSingleton}().someMethod()
\end{DoxyCode}
 \hypertarget{_the-_core-_objects_The-Mesh-Object}{}\subsection{The Mesh Object}\label{_the-_core-_objects_The-Mesh-Object}
A \hyperlink{class_ogre_1_1_mesh}{Ogre\+::\+Mesh} object represents a discrete model, a set of geometry which is self-\/contained and is typically fairly small on a world scale. \hyperlink{class_ogre_1_1_mesh}{Ogre\+::\+Mesh} objects are assumed to represent movable objects and are not used for the sprawling level geometry typically used to create backgrounds.

\hyperlink{class_ogre_1_1_mesh}{Ogre\+::\+Mesh} objects are a type of resource, and are managed by the Mesh\+Manager resource manager. They are typically loaded from O\+G\+R\+E’s custom object format, the ’.\+mesh’ format. Mesh files are typically created by exporting from a modelling tool See \hyperlink{_mesh-_tools_Exporters}{Exporters} and can be manipulated through various \hyperlink{Mesh-Tools}{Mesh Tools}

You can also create Mesh objects manually by calling the \hyperlink{class_ogre_1_1_mesh_manager_ad99f5f2e2d045e5a4af301974e45c918}{Ogre\+::\+Mesh\+Manager\+::create\+Manual} method. This way you can define the geometry yourself, but this is outside the scope of this manual.

Mesh objects are the basis for the individual movable objects in the world, which are called \hyperlink{_the-_core-_objects_Entities}{Entities}.

Mesh objects can also be animated using See \hyperlink{_animation_Skeletal-Animation}{Skeletal Animation}.\hypertarget{_the-_core-_objects_Entities}{}\subsection{Entities}\label{_the-_core-_objects_Entities}
An entity is an instance of a movable object in the scene. It could be a car, a person, a dog, a shuriken, whatever. The only assumption is that it does not necessarily have a fixed position in the world.

Entities are based on discrete meshes, i.\+e. collections of geometry which are self-\/contained and typically fairly small on a world scale, which are represented by the \hyperlink{class_ogre_1_1_mesh}{Ogre\+::\+Mesh} object. Multiple entities can be based on the same mesh, since often you want to create multiple copies of the same type of object in a scene.

You create an entity by calling the \hyperlink{class_ogre_1_1_scene_manager_afb393cca49de8b928f7dd60838047185}{Ogre\+::\+Scene\+Manager\+::create\+Entity} method, giving it a name and specifying the name of the mesh object which it will be based on (e.\+g. ’muscleboundhero.\+mesh’). The \hyperlink{class_ogre_1_1_scene_manager}{Ogre\+::\+Scene\+Manager} will ensure that the mesh is loaded by calling the \hyperlink{class_ogre_1_1_mesh_manager}{Ogre\+::\+Mesh\+Manager} resource manager for you. Only one copy of the Mesh will be loaded.

Ogre\+::\+Entities are not deemed to be a part of the scene until you attach them to a \hyperlink{class_ogre_1_1_scene_node}{Ogre\+::\+Scene\+Node} (see the section below). By attaching entities to Scene\+Nodes, you can create complex hierarchical relationships between the positions and orientations of entities. You then modify the positions of the nodes to indirectly affect the entity positions.

When a \hyperlink{class_ogre_1_1_mesh}{Ogre\+::\+Mesh} is loaded, it automatically comes with a number of materials defined. It is possible to have more than one material attached to a mesh -\/ different parts of the mesh may use different materials. Any entity created from the mesh will automatically use the default materials. However, you can change this on a per-\/entity basis if you like so you can create a number of entities based on the same mesh but with different textures etc.

To understand how this works, you have to know that all Mesh objects are actually composed of \hyperlink{class_ogre_1_1_sub_mesh}{Ogre\+::\+Sub\+Mesh} objects, each of which represents a part of the mesh using one Material. If a \hyperlink{class_ogre_1_1_mesh}{Ogre\+::\+Mesh} uses only one \hyperlink{class_ogre_1_1_material}{Ogre\+::\+Material}, it will only have one \hyperlink{class_ogre_1_1_sub_mesh}{Ogre\+::\+Sub\+Mesh}.

When an \hyperlink{class_ogre_1_1_entity}{Ogre\+::\+Entity} is created based on this Mesh, it is composed of (possibly) multiple \hyperlink{class_ogre_1_1_sub_entity}{Ogre\+::\+Sub\+Entity} objects, each matching 1 for 1 with the \hyperlink{class_ogre_1_1_sub_mesh}{Ogre\+::\+Sub\+Mesh} objects from the original Mesh. You can access the \hyperlink{class_ogre_1_1_sub_entity}{Ogre\+::\+Sub\+Entity} objects using the \hyperlink{class_ogre_1_1_entity_a23fc34c5e2eff03aae4cbf800c142724}{Ogre\+::\+Entity\+::get\+Sub\+Entity} method. Once you have a reference to a \hyperlink{class_ogre_1_1_sub_entity}{Ogre\+::\+Sub\+Entity}, you can change the material it uses by calling it’s set\+Material\+Name method. In this way you can make an \hyperlink{class_ogre_1_1_entity}{Ogre\+::\+Entity} deviate from the default materials and thus create an individual looking version of it.\hypertarget{_the-_core-_objects_Materials}{}\subsection{Materials}\label{_the-_core-_objects_Materials}
The \hyperlink{class_ogre_1_1_material}{Ogre\+::\+Material} object controls how objects in the scene are rendered. It specifies what basic surface properties objects have such as reflectance of colours, shininess etc, how many texture layers are present, what images are on them and how they are blended together, what special effects are applied such as environment mapping, what culling mode is used, how the textures are filtered etc.

Materials can either be set up programmatically, by calling \hyperlink{class_ogre_1_1_material_manager_a3068599a5b10421e6203d568006f5f93}{Ogre\+::\+Material\+Manager\+::create} and tweaking the settings, or by specifying it in a ’script’ which is loaded at runtime. See \hyperlink{Material-Scripts}{Material Scripts} for more info.

Basically everything about the appearance of an object apart from it’s shape is controlled by the Material class.

The Scene\+Manager class manages the master list of materials available to the scene. The list can be added to by the application by calling \hyperlink{class_ogre_1_1_material_manager_a3068599a5b10421e6203d568006f5f93}{Ogre\+::\+Material\+Manager\+::create}, or by loading a Mesh (which will in turn load material properties). Whenever materials are added to the Scene\+Manager, they start off with a default set of properties; these are defined by O\+G\+RE as the following\+:


\begin{DoxyItemize}
\item ambient reflectance = Colour\+Value\+::\+White (full)
\item diffuse reflectance = Colour\+Value\+::\+White (full)
\item specular reflectance = Colour\+Value\+::\+Black (none)
\item emissive = Colour\+Value\+::\+Black (none)
\item shininess = 0 (not shiny)
\item No texture layers (\& hence no textures)
\item Source\+Blend\+Factor = S\+B\+F\+\_\+\+O\+NE, Dest\+Blend\+Factor = S\+B\+F\+\_\+\+Z\+E\+RO (opaque)
\item Depth buffer checking on
\item Depth buffer writing on
\item Depth buffer comparison function = C\+M\+P\+F\+\_\+\+L\+E\+S\+S\+\_\+\+E\+Q\+U\+AL
\item Culling mode = C\+U\+L\+L\+\_\+\+C\+L\+O\+C\+K\+W\+I\+SE
\item Ambient lighting in scene = Colour\+Value(0.\+5, 0.\+5, 0.\+5) (mid-\/grey)
\item Dynamic lighting enabled
\item Gourad shading mode
\item Solid polygon mode
\item Bilinear texture filtering
\end{DoxyItemize}

You can alter these settings by calling \hyperlink{class_ogre_1_1_material_manager_ac70230fa9f123976d7f2b1257bd94bd4}{Ogre\+::\+Material\+Manager\+::get\+Default\+Settings()} and making the required changes to the Material which is returned.

Entities automatically have Material’s associated with them if they use a \hyperlink{class_ogre_1_1_mesh}{Ogre\+::\+Mesh} object, since the \hyperlink{class_ogre_1_1_mesh}{Ogre\+::\+Mesh} object typically sets up it’s required materials on loading. You can also customise the material used by an entity as described in \hyperlink{_the-_core-_objects_Entities}{Entities}. Just create a new Material, set it up how you like (you can copy an existing material into it if you like using a standard assignment statement) and point the Sub\+Entity entries at it using \hyperlink{class_ogre_1_1_sub_entity_ab8af6685128c68a5d7863bb5238ebc0f}{Ogre\+::\+Sub\+Entity\+::set\+Material\+Name()}.\hypertarget{_the-_core-_objects_Overlays}{}\subsection{Overlays}\label{_the-_core-_objects_Overlays}
Overlays allow you to render 2D and 3D elements on top of the normal scene contents to create effects like heads-\/up displays (H\+U\+Ds), menu systems, status panels etc. The frame rate statistics panel which comes as standard with O\+G\+RE is an example of an overlay. Overlays can contain 2D or 3D elements. 2D elements are used for H\+U\+Ds, and 3D elements can be used to create cockpits or any other 3D object which you wish to be rendered on top of the rest of the scene.

You can create overlays either through the \hyperlink{class_ogre_1_1_overlay_manager_ab6eb3dcc484ba5b06904ab2fb6b1aa23}{Ogre\+::\+Overlay\+Manager\+::create} method, or you can define them in an .overlay script. See \hyperlink{Overlay-Scripts}{Overlay Scripts} for more info. In reality the latter is likely to be the most practical because it is easier to tweak (without the need to recompile the code). Note that you can define as many overlays as you like\+: they all start off life hidden, and you display them by calling \hyperlink{class_ogre_1_1_overlay_a3c565f3e5cf61f43fa33542d713e8ccf}{Ogre\+::\+Overlay\+::show}. You can also show multiple overlays at once, and their Z order is determined by the \hyperlink{class_ogre_1_1_overlay_a5d8481d5fa0990846e53345f1a1cc705}{Ogre\+::\+Overlay\+::set\+Z\+Order()} method.

\label{_Notes-on-Integration}%


\subsection*{Notes on Integration}

The Overlay\+System is its own component, you need to manually initialize it, with the following two lines of code (m\+Scene\+Mgr is a pointer to your current \hyperlink{class_ogre_1_1_scene_manager}{Ogre\+::\+Scene\+Manager})\+:


\begin{DoxyCode}
\hyperlink{class_ogre_1_1_overlay_system}{Ogre::OverlaySystem}* pOverlaySystem = \textcolor{keyword}{new} \hyperlink{class_ogre_1_1_overlay_system}{Ogre::OverlaySystem}();
mSceneMgr->addRenderQueueListener(pOverlaySystem);
\end{DoxyCode}


One \hyperlink{class_ogre_1_1_overlay_system}{Ogre\+::\+Overlay\+System} per application is enough but you need to call add\+Render\+Queue\+Listener once per Scene\+Manager.

\label{_Creating-2D-Elements}%


\subsection*{Creating 2D Elements}

The \hyperlink{class_ogre_1_1_overlay_element}{Ogre\+::\+Overlay\+Element} class abstracts the details of 2D elements which are added to overlays. All items which can be added to overlays are derived from this class. It is possible (and encouraged) for users of O\+G\+RE to define their own custom subclasses of Overlay\+Element in order to provide their own user controls. The key common features of all Overlay\+Elements are things like size, position, basic material name etc. Subclasses extend this behaviour to include more complex properties and behaviour.

An important built-\/in subclass of Overlay\+Element is \hyperlink{class_ogre_1_1_overlay_container}{Ogre\+::\+Overlay\+Container}. Overlay\+Container is the same as a Overlay\+Element, except that it can contain other Overlay\+Elements, grouping them together (allowing them to be moved together for example) and providing them with a local coordinate origin for easier lineup.

The third important class is \hyperlink{class_ogre_1_1_overlay_manager}{Ogre\+::\+Overlay\+Manager}. Whenever an application wishes to create a 2D element to add to an overlay (or a container), it should call \hyperlink{class_ogre_1_1_overlay_manager_a58166a773d27c22437323e8ef710406b}{Ogre\+::\+Overlay\+Manager\+::create\+Overlay\+Element}. The type of element you wish to create is identified by a string, the reason being that it allows plugins to register new types of Overlay\+Element for you to create without you having to link specifically to those libraries. For example, to create a panel (a plain rectangular area which can contain other Overlay\+Elements) you would call {\ttfamily Overlay\+Manager\+::get\+Singleton().create\+Overlay\+Element(\char`\"{}\+Panel\char`\"{}, \char`\"{}my\+New\+Panel\char`\"{});}.

\label{_Adding-2D-Elements-to-the-Overlay}%


\subsection*{Adding 2D Elements to the Overlay}

Only Overlay\+Containers can be added direct to an overlay. The reason is that each level of container establishes the Zorder of the elements contained within it, so if you nest several containers, inner containers have a higher Z-\/order than outer ones to ensure they are displayed correctly. To add a container (such as a Panel) to the overlay, simply call \hyperlink{class_ogre_1_1_overlay_a702b15ebaa6d3f8dbb2918500b76c9f0}{Ogre\+::\+Overlay\+::add2D}.

If you wish to add child elements to that container, call \hyperlink{class_ogre_1_1_overlay_container_aa9eec8f6dca98ac61766fc4785b84661}{Ogre\+::\+Overlay\+Container\+::add\+Child}. Child elements can be Ogre\+::\+Overlay\+Elements or \hyperlink{class_ogre_1_1_overlay_container}{Ogre\+::\+Overlay\+Container} instances themselves. Remember that the position of a child element is relative to the top-\/left corner of it’s parent.

\label{_A-word-about-2D-coordinates}%


\subsection*{A word about 2D coordinates}

O\+G\+RE allows you to place and size elements based on 2 coordinate systems\+: {\bfseries relative} and {\bfseries pixel} based.


\begin{DoxyDescription}
\item[Pixel Mode ]

This mode is useful when you want to specify an exact size for your overlay items, and you don’t mind if those items get smaller on the screen if you increase the screen resolution (in fact you might want this). In this mode the only way to put something in the middle or at the right or bottom of the screen reliably in any resolution is to use the aligning options, whilst in relative mode you can do it just by using the right relative coordinates. This mode is very simple, the top-\/left of the screen is (0,0) and the bottom-\/right of the screen depends on the resolution. As mentioned above, you can use the aligning options to make the horizontal and vertical coordinate origins the right, bottom or center of the screen if you want to place pixel items in these locations without knowing the resolution.


\item[Relative Mode ]

This mode is useful when you want items in the overlay to be the same size on the screen no matter what the resolution. In relative mode, the top-\/left of the screen is (0,0) and the bottom-\/right is (1,1). So if you place an element at (0.\+5, 0.\+5), it’s top-\/left corner is placed exactly in the center of the screen, no matter what resolution the application is running in. The same principle applies to sizes; if you set the width of an element to 0.\+5, it covers half the width of the screen. Note that because the aspect ratio of the screen is typically 1.\+3333 \+: 1 (width \+: height), an element with dimensions (0.\+25, 0.\+25) will not be square, but it will take up exactly 1/16th of the screen in area terms. If you want square-\/looking areas you will have to compensate using the typical aspect ratio e.\+g. use (0.\+1875, 0.\+25) instead.


\end{DoxyDescription}

\label{_Transforming-Overlays}%
 \subsection*{Transforming Overlays}

Another nice feature of overlays is being able to rotate, scroll and scale them as a whole. You can use this for zooming in / out menu systems, dropping them in from off screen and other nice effects. See the \hyperlink{class_ogre_1_1_overlay_ae07b1a57498aad0299f0781b09ca9b39}{Ogre\+::\+Overlay\+::scroll}, \hyperlink{class_ogre_1_1_overlay_a8282553a59253170ddd0488ab7179792}{Ogre\+::\+Overlay\+::rotate} and \hyperlink{class_ogre_1_1_overlay_adea3b88baa3697a657e7b5785f0ffedb}{Ogre\+::\+Overlay\+::set\+Scale} methods for more information.

\label{_GUI-systems}%


\subsection*{G\+UI systems}

Overlays are only really designed for non-\/interactive screen elements, although you can create a simple G\+UI using the \hyperlink{trays}{Trays System}. For a far more complete G\+UI solution, we recommend or \href{https://github.com/OGRECave/ogre-imgui}{\tt Dear Im\+Gui}, \href{http://www.cegui.org.uk}{\tt C\+E\+Gui} or \href{http://mygui.info/}{\tt My\+G\+UI}. \hypertarget{Scripts}{}\section{Scripts}\label{Scripts}
O\+G\+RE drives many of its features through scripts in order to make it easier to set up. The scripts are simply plain text files which can be edited in any standard text editor, and modifying them immediately takes effect on your O\+G\+R\+E-\/based applications, without any need to recompile. This makes prototyping a lot faster. Here are the items that O\+G\+RE lets you script\+:


\begin{DoxyItemize}
\item \hyperlink{Material-Scripts}{Material Scripts}
\item \hyperlink{Compositor-Scripts}{Compositor Scripts}
\item \hyperlink{Particle-Scripts}{Particle Scripts}
\item \hyperlink{Overlay-Scripts}{Overlay Scripts}
\item \hyperlink{Font-Definition-Scripts}{Font Definition Scripts}
\end{DoxyItemize}

\section*{Loading scripts}

Scripts are loaded when resource groups are initialised\+: O\+G\+RE looks in all resource locations associated with the group (see \hyperlink{class_ogre_1_1_resource_group_manager_a6ff0efec5d27cedb448cfba8b2b78c8d}{Ogre\+::\+Resource\+Group\+Manager\+::add\+Resource\+Location}) for files with the respective extension (e.\+g. ’.\+material’, ’.\+compositor’, ..) and parses them. If you want to parse files manually, use the {\ttfamily parse\+Script} method of the according manager.\hypertarget{_scripts_Format}{}\subsection{Format}\label{_scripts_Format}
Several script objects may be defined in a single file. The script format is pseudo-\/\+C++, with sections delimited by curly braces (\{\}), and comments indicated by starting a line with ’//’. The general format is shown below\+:


\begin{DoxyCode}
\textcolor{comment}{// This is a comment}
object\_keyword Example/ObjectName
\{
    attribute\_name \textcolor{stringliteral}{"some value"}

    object\_keyword2 \textcolor{stringliteral}{"Nested Object"}
    \{
        other\_attribute 1 2 3
        \textcolor{comment}{// and so on..}
    \}
\}
\end{DoxyCode}


Every script object must be given a name, which is the line ’object\+\_\+keyword $<$name$>$’ before the first opening ’\{’. This name must be globally unique. It can include path characters (as in the example) to logically divide up the objects, and also to avoid duplicate names, but the engine does not treat the name as hierarchical, just as a string. Names can include spaces but must be surrounded by double quotes i.\+e. {\ttfamily compositor \char`\"{}\+My Name\char`\"{}}.

\begin{DoxyNote}{Note}
’\+:’ is the delimiter for specifying inheritance in the script so it can’t be used as part of the name.
\end{DoxyNote}
An script object can inherit from a previously defined object by using a {\itshape colon} ’\+:’ after the name followed by the name of the reference object to inherit from. You can in fact even inherit just {\itshape parts} of a script object from others; all this is covered in \hyperlink{_scripts_Script-Inheritance}{Script Inheritance}). You can also use variables in your script which can be replaced in inheriting versions, see \hyperlink{_scripts_Script-Variables}{Script Variables}.\hypertarget{_scripts_Script-Inheritance}{}\subsubsection{Script Inheritance}\label{_scripts_Script-Inheritance}
When creating new script objects that are only slight variations of another object, it’s good to avoid copying and pasting between scripts. Script inheritance lets you do this; in this section we’ll use material scripts as an example, but this applies to all scripts parsed with the script compilers in \hyperlink{namespace_ogre}{Ogre} 1.\+6 onwards.

For example, to make a new material that is based on one previously defined, add a {\itshape colon} ’\+:’ after the new material name followed by the name of the material that is to be copied.

Example 
\begin{DoxyCode}
material <NewUniqueChildName> : <ReferenceParentMaterial>
\end{DoxyCode}


The only caveat is that a parent material must have been defined/parsed prior to the child material script being parsed. The easiest way to achieve this is to either place parents at the beginning of the material script file, or to use the ’import’ directive (See \hyperlink{_scripts_Script-Import-Directive}{Script Import Directive}). Note that inheritance is actually a copy -\/ after scripts are loaded into \hyperlink{namespace_ogre}{Ogre}, objects no longer maintain their copy inheritance structure. If a parent material is modified through code at runtime, the changes have no effect on child materials that were copied from it in the script.

Material copying within the script alleviates some drudgery from copy/paste but having the ability to identify specific techniques, passes, and texture units to modify makes material copying easier. Techniques, passes, texture units can be identified directly in the child material without having to layout previous techniques, passes, texture units by associating a name with them, Techniques and passes can take a name and texture units can be numbered within the material script. You can also use variables, See \hyperlink{_scripts_Script-Variables}{Script Variables}.

Names become very useful in materials that copy from other materials. In order to override values they must be in the correct technique, pass, texture unit etc. The script could be lain out using the sequence of techniques, passes, texture units in the child material but if only one parameter needs to change in say the 5th pass then the first four passes prior to the fifth would have to be placed in the script\+:

Here is an example\+:


\begin{DoxyCode}
material test2 : test1
\{
  technique
  \{
    pass
    \{
    \}

    pass
    \{
    \}

    pass
    \{
    \}

    pass
    \{
    \}

    pass
    \{
      ambient 0.5 0.7 0.3 1.0
    \}
  \}
\}
\end{DoxyCode}


This method is tedious for materials that only have slight variations to their parent. An easier way is to name the pass directly without listing the previous passes\+:~\newline



\begin{DoxyCode}
material test2 : test1
\{
  technique
  \{
    pass \textcolor{stringliteral}{"Fifth Pass"}
    \{
      ambient 0.5 0.7 0.3 1.0
    \}
  \}
\}
\end{DoxyCode}


The parent pass name must be known and the pass must be in the correct technique in order for this to work correctly. Specifying the technique name and the pass name is the best method.\hypertarget{_scripts_Advanced-Script-Inheritance}{}\paragraph{Advanced Script Inheritance}\label{_scripts_Advanced-Script-Inheritance}
Script objects can also inherit from each other more generally. The previous concept of inheritance, material copying, was restricted only to the top-\/level material objects. Now, any level of object can take advantage of inheritance (for instance, techniques, passes, and compositor targets).


\begin{DoxyCode}
material Test
\{
    technique
    \{
        pass : ParentPass
        \{
        \}
    \}
\}
\end{DoxyCode}


Notice that the pass inherits from Parent\+Pass. This allows for the creation of more fine-\/grained inheritance hierarchies.

Along with the more generalized inheritance system comes an important new keyword\+: \char`\"{}abstract.\char`\"{} This keyword is used at a top-\/level object declaration (not inside any other object) to denote that it is not something that the compiler should actually attempt to compile, but rather that it is only for the purpose of inheritance. For example, a material declared with the abstract keyword will never be turned into an actual usable material in the material framework. Objects which cannot be at a top-\/level in the document (like a pass) but that you would like to declare as such for inheriting purpose must be declared with the abstract keyword.


\begin{DoxyCode}
\textcolor{keyword}{abstract} pass ParentPass
\{
    diffuse 1 0 0 1
\}
\end{DoxyCode}


That declares the Parent\+Pass object which was inherited from in the above example. Notice the abstract keyword which informs the compiler that it should not attempt to actually turn this object into any sort of \hyperlink{namespace_ogre}{Ogre} resource. If it did attempt to do so, then it would obviously fail, since a pass all on its own like that is not valid.

The final matching option is based on wildcards. Using the ’$\ast$’ character, you can make a powerful matching scheme and override multiple objects at once, even if you don’t know exact names or positions of those objects in the inherited object.


\begin{DoxyCode}
\textcolor{keyword}{abstract} technique Overrider
\{
   pass *colour*
   \{
      diffuse 0 0 0 0
   \}
\}
\end{DoxyCode}


This technique, when included in a material, will override all passes matching the wildcard \char`\"{}\textbackslash{}$\ast$color\textbackslash{}$\ast$\char`\"{} (color has to appear in the name somewhere) and turn their diffuse properties black. It does not matter their position or exact name in the inherited technique, this will match them.\hypertarget{_scripts_Script-Variables}{}\subsubsection{Script Variables}\label{_scripts_Script-Variables}
A very powerful new feature in \hyperlink{namespace_ogre}{Ogre} 1.\+6 is variables. Variables allow you to parameterize data in materials so that they can become more generalized. This enables greater reuse of scripts by targeting specific customization points. Using variables along with inheritance allows for huge amounts of overrides and easy object reuse.


\begin{DoxyCode}
\textcolor{keyword}{abstract} pass ParentPass
\{
   diffuse $diffuse\_colour
\}

material Test
\{
   technique
   \{
       pass : ParentPass
       \{
           \textcolor{keyword}{set} $diffuse\_colour \textcolor{stringliteral}{"1 0 0 1"}
       \}
   \}
\}
\end{DoxyCode}


The Parent\+Pass object declares a variable called \char`\"{}diffuse\textbackslash{}\+\_\+colour\char`\"{} which is then overridden in the Test material’s pass. The \char`\"{}set\char`\"{} keyword is used to set the value of that variable. The variable assignment follows lexical scoping rules, which means that the value of \char`\"{}1 0 0 1\char`\"{} is only valid inside that pass definition. Variable assignment in outer scopes carry over into inner scopes.


\begin{DoxyCode}
material Test
\{
    \textcolor{keyword}{set} $diffuse\_colour \textcolor{stringliteral}{"1 0 0 1"}
    technique
    \{
        pass : ParentPass
        \{
        \}
    \}
\}
\end{DoxyCode}


The \$diffuse\+\_\+colour assignment carries down through the technique and into the pass.\hypertarget{_scripts_Script-Import-Directive}{}\subsubsection{Script Import Directive}\label{_scripts_Script-Import-Directive}
Imports are a feature introduced to remove ambiguity from script dependencies. When using scripts that inherit from each other but which are defined in separate files sometimes errors occur because the scripts are loaded in incorrect order. Using imports removes this issue. The script which is inheriting another can explicitly import its parent’s definition which will ensure that no errors occur because the parent’s definition was not found.


\begin{DoxyCode}
\textcolor{keyword}{import} * from \textcolor{stringliteral}{"parent.material"}
material Child : Parent
\{
\}
\end{DoxyCode}


The material \char`\"{}\+Parent\char`\"{} is defined in parent.\+material and the import ensures that those definitions are found properly. You can also import specific targets from within a file.


\begin{DoxyCode}
\textcolor{keyword}{import} Parent from \textcolor{stringliteral}{"parent.material"}
\end{DoxyCode}


If there were other definitions in the parent.\+material file, they would not be imported.

Note, however that importing does not actually cause objects in the imported script to be fully parsed \& created, it just makes the definitions available for inheritance. This has a specific ramification for vertex / fragment program definitions, which must be loaded before any parameters can be specified. You should continue to put common program definitions in .program files to ensure they are fully parsed before being referenced in multiple .material files. The ’import’ command just makes sure you can resolve dependencies between equivalent script definitions (e.\+g. material to material).\hypertarget{_scripts_custom-translators}{}\subsection{Custom Translators}\label{_scripts_custom-translators}
Writing a custom translators allows you to extend \hyperlink{namespace_ogre}{Ogre}\textquotesingle{}s standard compilers with completely new functionality. The same scripting interfaces can be used to define application-\/specific functionality. Here\textquotesingle{}s how you do it.

The first step is creating a custom translator class which extends \hyperlink{class_ogre_1_1_script_translator}{Ogre\+::\+Script\+Translator}.


\begin{DoxyCodeInclude}
\textcolor{keyword}{struct }FontTranslator : \textcolor{keyword}{public} ScriptTranslator
\{
    \textcolor{keywordtype}{void} translate(ScriptCompiler* compiler, \textcolor{keyword}{const} \hyperlink{group___general_ga15cfb375beeafed87e1bdd96ef10ff36}{AbstractNodePtr}& node);
    \textcolor{keywordtype}{void} parseAttribute(ScriptCompiler* compiler, \hyperlink{group___overlays_ga6fc186106cde55e3a7b867798fe28e89}{FontPtr}& pFont, PropertyAbstractNode* prop);
\};
\end{DoxyCodeInclude}
 This class defines the important function to override\+: translate. This is called when the Test\+Translator needs to process a sub-\/set of the parsed script. The definition of this function might look something like this\+:


\begin{DoxyCodeInclude}
\textcolor{keywordtype}{void} FontTranslator::translate(ScriptCompiler* compiler, \textcolor{keyword}{const} \hyperlink{group___general_ga15cfb375beeafed87e1bdd96ef10ff36}{AbstractNodePtr}& node)
\{
    ObjectAbstractNode* obj = \textcolor{keyword}{static\_cast<}ObjectAbstractNode*\textcolor{keyword}{>}(node.get());

    \textcolor{comment}{// Must have a name - unless we are in legacy mode. Then the class is the name.}
    \textcolor{keywordflow}{if} (obj->name.empty() && obj->cls == \textcolor{stringliteral}{"font"})
    \{
        compiler->addError(ScriptCompiler::CE\_OBJECTNAMEEXPECTED, obj->file, obj->line,
                           \textcolor{stringliteral}{"font must be given a name"});
        \textcolor{keywordflow}{return};
    \}

    \hyperlink{namespace_ogre_af73bbdc8bed8a3e6fcd56bb8fa188c45}{String}& name = obj->cls == \textcolor{stringliteral}{"font"} ? obj->name : obj->cls;

    \hyperlink{group___overlays_ga6fc186106cde55e3a7b867798fe28e89}{FontPtr} font = FontManager::getSingleton().create(name, compiler->getResourceGroup());
    font->\hyperlink{class_ogre_1_1_resource_a7e248a1cca0662418d4ab3f63c2e7cf6}{\_notifyOrigin}(obj->file);

    \textcolor{keywordflow}{for} (\textcolor{keyword}{auto}& c : obj->children)
    \{
        \textcolor{keywordflow}{if} (c->type == \hyperlink{group___general_gga788dd054963542ec3375d9b83255bc98aea41df7725177862840cf90b4016008a}{ANT\_PROPERTY})
        \{
            parseAttribute(compiler, font, static\_cast<PropertyAbstractNode*>(c.get()));
        \}
    \}
\}
\end{DoxyCodeInclude}
 The translate function here expects all children to be atomic properties. Sub-\/objects can also be processed by checking if the child node type is \hyperlink{group___general_gga788dd054963542ec3375d9b83255bc98a235f619027a81559883aba536d1a3cd6}{Ogre\+::\+A\+N\+T\+\_\+\+O\+B\+J\+E\+CT}.

From here you need to register the translator to be invoked when the proper object is found in the scripts. To do this we need to create a \hyperlink{class_ogre_1_1_script_translator_manager}{Ogre\+::\+Script\+Translator\+Manager} object to create your custom translator. The relevant parts look like this\+:


\begin{DoxyCodeInclude}
    ScriptCompilerManager::getSingleton().addTranslatorManager(\textcolor{keyword}{this});
    ID\_FONT = ScriptCompilerManager::getSingleton().registerCustomWordId(\textcolor{stringliteral}{"font"});
\end{DoxyCodeInclude}
 Note how we use \hyperlink{class_ogre_1_1_script_compiler_manager_af3f78dbda6c8200e06a6d72981e3de92}{Ogre\+::\+Script\+Compiler\+Manager\+::register\+Custom\+Word\+Id} to avoid string comparisons in our code.


\begin{DoxyCodeInclude}
ScriptTranslator* OverlayTranslatorManager::getTranslator(\textcolor{keyword}{const} \hyperlink{group___general_ga15cfb375beeafed87e1bdd96ef10ff36}{AbstractNodePtr}& node)
\{
    \textcolor{keywordflow}{if} (node->type != \hyperlink{group___general_gga788dd054963542ec3375d9b83255bc98a235f619027a81559883aba536d1a3cd6}{ANT\_OBJECT})
        \textcolor{keywordflow}{return} NULL;

    ObjectAbstractNode* obj = \textcolor{keyword}{static\_cast<}ObjectAbstractNode*\textcolor{keyword}{>}(node.get());

    \textcolor{keywordflow}{if} (obj->id == ID\_FONT)
        \textcolor{keywordflow}{return} &mFontTranslator;
\end{DoxyCodeInclude}
 No new translators are created here, just returned when requested. This is because our translator does not require separate instances to properly parse scripts, and so it is easier to only create one instance and reuse it. Often this strategy will work.

The order that custom translator managers are registered will make a difference. When the system is attempting to find translators to handle pieces of a script, it will query the translator managers one-\/by-\/one until it finds one that handles that script object. It is a first-\/come-\/first-\/served basis.

An important note is that this will recognize the above pattern no matter where in the script it is. That means that this may appear at the top-\/level of a script or inside several sub-\/objects. If this is not what you want then you can change the translator manager to do more advanced processing in the get\+Translator function. \hypertarget{Material-Scripts}{}\subsection{Material Scripts}\label{Material-Scripts}
Sets the specific operation used to blend source and destination pixels together.

Material scripts offer you the ability to define complex materials in a script which can be reused easily. Whilst you could set up all materials for a scene in code using the methods of the Material and Texture\+Layer classes, in practice it\textquotesingle{}s a bit unwieldy. Instead you can store material definitions in text files which can then be loaded whenever required.

It’s important to realise that materials are not loaded completely by the parsing process\+: only the definition is loaded, no textures or other resources are loaded. This is because it is common to have a large library of materials, but only use a relatively small subset of them in any one scene. To load every material completely in every script would therefore cause unnecessary memory overhead. You can access a ’deferred load’ Material in the normal way (\hyperlink{class_ogre_1_1_material_manager_a100f413d9d2316028e7ae740e5a43161}{Ogre\+::\+Material\+Manager\+::get\+Singleton()}.get\+By\+Name()), but you must call the ’load’ method before trying to use it. \hyperlink{namespace_ogre}{Ogre} does this for you when using the normal material assignment methods of entities etc.

To start with, we only consider fixed-\/function materials which don’t use vertex, geometry or fragment programs, these are covered later\+:


\begin{DoxyCode}
\textcolor{comment}{// This is a comment}
material walls/funkywall1
\{
    \textcolor{comment}{// first, preferred technique}
    technique
    \{
        \textcolor{comment}{// first pass}
        pass
        \{
            ambient 0.5 0.5 0.5
            diffuse 1.0 1.0 1.0

            \textcolor{comment}{// Texture unit 0}
            texture\_unit 
            \{
                texture wibbly.jpg
                scroll\_anim 0.1 0.0
                wave\_xform scale sine 0.0 0.7 0.0 1.0
            \}
            \textcolor{comment}{// Texture unit 1 (this is a multitexture pass)}
            texture\_unit
            \{
                texture wobbly.png
                rotate\_anim 0.25
                colour\_op add
            \}

            \textcolor{comment}{// Additional RT Shader system options}
            rtshader\_system
            \{
                \textcolor{comment}{// Do lighting calculations per-pixel }
                lighting\_stage per\_pixel
            \}
        \}
    \}

    \textcolor{comment}{// Second technique, can be used as a fallback or LOD level}
    technique
    \{
        \textcolor{comment}{// .. and so on}
    \}   
\}
\end{DoxyCode}


A material can be made up of many \hyperlink{_material-_scripts_Techniques}{Techniques} -\/ a technique is one way of achieving the effect you are looking for. You can supply more than one technique in order to provide fallback approaches where a card does not have the ability to render the preferred technique, or where you wish to define lower level of detail versions of the material in order to conserve rendering power when objects are more distant.

Each technique can be made up of many \hyperlink{_material-_scripts_Passes}{Passes}, that is a complete render of the object can be performed multiple times with different settings in order to produce composite effects. \hyperlink{namespace_ogre}{Ogre} may also split the passes you have defined into many passes at runtime, if you define a pass which uses too many texture units for the card you are currently running on (note that it can only do this if you are not using a fragment program). Each pass has a number of top-\/level attributes such as ’ambient’ to set the amount \& colour of the ambient light reflected by the material. Some of these options do not apply if you are using vertex programs, See \hyperlink{_material-_scripts_Passes}{Passes} for more details.

Within each pass, there can be zero or many \hyperlink{_material-_scripts_Texture-Units}{Texture Units} in use. These define the texture to be used, and optionally some blending operations (which use multitexturing) and texture effects.

You can also reference vertex and fragment programs (or vertex and pixel shaders, if you want to use that terminology) in a pass with a given set of parameters. Programs themselves are declared in separate .program scripts (See \hyperlink{_material-_scripts_Declaring-Vertex_002fGeometry_002fFragment-Programs}{Declaring G\+PU Programs}) and are used as described in \hyperlink{_high-level-_programs_Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass}{Using G\+PU Programs in a Pass}.

\label{_Top_002dlevel-material-attributes}%
\hypertarget{_material-_scripts_Material}{}\subsubsection{Material}\label{_material-_scripts_Material}
The outermost section of a material definition does not have a lot of attributes of its own (most of the configurable parameters are within the child sections. However, it does have some, and here they are\+:

\label{_lod_005fstrategy}%
 \label{_lod_005fstrategy-1}%


\subsection*{lod\+\_\+strategy}

Sets the name of the L\+OD strategy to use. Defaults to ’\+Distance’ which means L\+OD changes based on distance from the camera. Also supported is ’\+Pixel\+Count’ which changes L\+OD based on an estimate of the screen-\/space pixels affected. \begin{DoxyParagraph}{}
Format\+: lod\+\_\+strategy $<$name$>$~\newline
 Default\+: lod\+\_\+strategy Distance
\end{DoxyParagraph}
\label{_lod_005fvalues}%
 \label{_lod_005fvalues-1}%


\subsection*{lod\+\_\+values}

This attribute defines the values used to control the L\+OD transition for this material. By setting this attribute, you indicate that you want this material to alter the Technique that it uses based on some metric, such as the distance from the camera, or the approximate screen space coverage. The exact meaning of these values is determined by the option you select for \href{#lod_005fstrategy}{\tt lod\+\_\+strategy} -\/ it is a list of distances for the ’\+Distance’ strategy, and a list of pixel counts for the ’\+Pixel\+Count’ strategy, for example. You must give it a list of values, in order from highest L\+OD value to lowest L\+OD value, each one indicating the point at which the material will switch to the next L\+OD. Implicitly, all materials activate L\+OD index 0 for values less than the first entry, so you do not have to specify ’0’ at the start of the list. You must ensure that there is at least one Technique with a \href{#lod_005findex}{\tt lod\+\_\+index} value for each value in the list (so if you specify 3 values, you must have techniques for L\+OD indexes 0, 1, 2 and 3). Note you must always have at least one Technique at lod\+\_\+index 0.

\begin{DoxyParagraph}{}
Format\+: lod\+\_\+values $<$value0$>$ $<$value1$>$ $<$value2$>$ ...~\newline
 Default\+: none 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: ~\newline
 lod\+\_\+strategy Distance lod\+\_\+values 300.\+0 600.\+5 1200
\end{DoxyParagraph}
The above example would cause the material to use the best Technique at lod\+\_\+index 0 up to a distance of 300 world units, the best from lod\+\_\+index 1 from 300 up to 600, lod\+\_\+index 2 from 600 to 1200, and lod\+\_\+index 3 from 1200 upwards.

\label{_lod_005fdistances}%
 \subsection*{lod\+\_\+distances}

\begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000165}{Deprecated}]This option is deprecated in favour of \href{#lod_005fvalues}{\tt lod\+\_\+values} now. \end{DoxyRefDesc}


\label{_receive_005fshadows}%
\label{_receive_005fshadows-1}%


\subsection*{receive\+\_\+shadows}

This attribute controls whether objects using this material can have shadows cast upon them.

\begin{DoxyParagraph}{}
Format\+: receive\+\_\+shadows $<$on$\vert$off$>$~\newline
 Default\+: on
\end{DoxyParagraph}
Whether or not an object receives a shadow is the combination of a number of factors, See \hyperlink{Shadows}{Shadows} for full details; however this allows you to make a material opt-\/out of receiving shadows if required. Note that transparent materials never receive shadows so this option only has an effect on solid materials.

\label{_transparency_005fcasts_005fshadows}%
\label{_transparency_005fcasts_005fshadows-1}%


\subsection*{transparency\+\_\+casts\+\_\+shadows}

This attribute controls whether transparent materials can cast certain kinds of shadow.

\begin{DoxyParagraph}{}
Format\+: transparency\+\_\+casts\+\_\+shadows $<$on$\vert$off$>$~\newline
 Default\+: off
\end{DoxyParagraph}
Whether or not an object casts a shadow is the combination of a number of factors, See \hyperlink{Shadows}{Shadows} for full details; however this allows you to make a transparent material cast shadows, when it would otherwise not. For example, when using texture shadows, transparent materials are normally not rendered into the shadow texture because they should not block light. This flag overrides that.

\label{_set_005ftexture_005falias}%
\label{_set_005ftexture_005falias-1}%


\subsection*{set\+\_\+texture\+\_\+alias}

This attribute associates a texture alias with a texture name.

\begin{DoxyParagraph}{}
Format\+: set\+\_\+texture\+\_\+alias $<$alias name$>$ $<$texture name$>$
\end{DoxyParagraph}
This attribute can be used to set the textures used in texture unit states that were inherited from another material.(See \hyperlink{_material-_scripts_Texture-Aliases}{Texture Aliases})\hypertarget{_material-_scripts_Techniques}{}\subsubsection{Techniques}\label{_material-_scripts_Techniques}
A \char`\"{}technique\char`\"{} section in your material script encapsulates a single method of rendering an object. The simplest of material definitions only contains a single technique, however since PC hardware varies quite greatly in it’s capabilities, you can only do this if you are sure that every card for which you intend to target your application will support the capabilities which your technique requires. In addition, it can be useful to define simpler ways to render a material if you wish to use material L\+OD, such that more distant objects use a simpler, less performance-\/hungry technique.

When a material is used for the first time, it is ’compiled’. That involves scanning the techniques which have been defined, and marking which of them are supportable using the current rendering A\+PI and graphics card. If no techniques are supportable, your material will render as blank white. The compilation examines a number of things, such as\+:


\begin{DoxyItemize}
\item The number of texture\+\_\+unit entries in each pass~\newline
 Note that if the number of texture\+\_\+unit entries exceeds the number of texture units in the current graphics card, the technique may still be supportable so long as a fragment program is not being used. In this case, \hyperlink{namespace_ogre}{Ogre} will split the pass which has too many entries into multiple passes for the less capable card, and the multitexture blend will be turned into a multipass blend (See \href{#colour_005fop_005fmultipass_005ffallback}{\tt colour\+\_\+op\+\_\+multipass\+\_\+fallback}).
\item Whether vertex, geometry or fragment programs are used, and if so which syntax they use (e.\+g. vs\+\_\+1\+\_\+1, ps\+\_\+2\+\_\+x, arbfp1 etc.)
\item Other effects like cube mapping and dot3 blending
\item Whether the vendor or device name of the current graphics card matches some user-\/specified rules
\end{DoxyItemize}

~\newline


In a material script, techniques must be listed in order of preference, i.\+e. the earlier techniques are preferred over the later techniques. This normally means you will list your most advanced, most demanding techniques first in the script, and list fallbacks afterwards.

To help clearly identify what each technique is used for, the technique can be named but its optional. Techniques not named within the script will take on a name that is the technique index number. For example\+: the first technique in a material is index 0, its name would be \char`\"{}0\char`\"{} if it was not given a name in the script. The technique name must be unique within the material or else the final technique is the resulting merge of all techniques with the same name in the material. A warning message is posted in the Ogre.\+log if this occurs. Named techniques can help when inheriting a material and modifying an existing technique\+: (See \hyperlink{_scripts_Script-Inheritance}{Script Inheritance})

\begin{DoxyParagraph}{}
Format\+: technique name
\end{DoxyParagraph}
Techniques have only a small number of attributes of their own\+:


\begin{DoxyItemize}
\item \href{#scheme}{\tt scheme}
\item \href{#lod_005findex}{\tt lod\+\_\+index} (and also see \href{#lod_005fdistances}{\tt lod\+\_\+distances} in the parent material)
\item \href{#shadow_005fcaster_005fmaterial}{\tt shadow\+\_\+caster\+\_\+material}
\item \href{#shadow_005freceiver_005fmaterial}{\tt shadow\+\_\+receiver\+\_\+material}
\item \href{#gpu_005fvendor_005frule}{\tt gpu\+\_\+vendor\+\_\+rule}
\item \href{#gpu_005fdevice_005frule}{\tt gpu\+\_\+device\+\_\+rule}
\end{DoxyItemize}

\label{_scheme}%
\label{_scheme-1}%


\subsection*{scheme}

Sets the ’scheme’ this Technique belongs to. Material schemes are used to control top-\/level switching from one set of techniques to another. For example, you might use this to define ’high’, ’medium’ and ’low’ complexity levels on materials to allow a user to pick a performance / quality ratio. Another possibility is that you have a fully H\+D\+R-\/enabled pipeline for top machines, rendering all objects using unclamped shaders, and a simpler pipeline for others; this can be implemented using schemes. The active scheme is typically controlled at a viewport level, and the active one defaults to ’\+Default’.

\begin{DoxyParagraph}{}
Format\+: scheme $<$name$>$~\newline
 Example\+: scheme hdr~\newline
 Default\+: scheme Default
\end{DoxyParagraph}
\label{_lod_005findex}%
\label{_lod_005findex-1}%


\subsection*{lod\+\_\+index}

Sets the level-\/of-\/detail (L\+OD) index this Technique belongs to.

\begin{DoxyParagraph}{}
Format\+: lod\+\_\+index $<$number$>$~\newline
 NB Valid values are 0 (highest level of detail) to 65535, although this is unlikely. You should not leave gaps in the L\+OD indexes between Techniques.
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: lod\+\_\+index 1
\end{DoxyParagraph}
All techniques must belong to a L\+OD index, by default they all belong to index 0, i.\+e. the highest L\+OD. Increasing indexes denote lower levels of detail. You can (and often will) assign more than one technique to the same L\+OD index, what this means is that O\+G\+RE will pick the best technique of the ones listed at the same L\+OD index. For readability, it is advised that you list your techniques in order of L\+OD, then in order of preference, although the latter is the only prerequisite (O\+G\+RE determines which one is ’best’ by which one is listed first). You must always have at least one Technique at lod\+\_\+index 0. The distance at which a L\+OD level is applied is determined by the lod\+\_\+distances attribute of the containing material, See \href{#lod_005fdistances}{\tt lod\+\_\+distances} for details.

\begin{DoxyParagraph}{}
Default\+: lod\+\_\+index 0
\end{DoxyParagraph}
Techniques also contain one or more \hyperlink{_material-_scripts_Passes}{Passes} (and there must be at least one).

\label{_shadow_005fcaster_005fmaterial}%
\label{_shadow_005fcaster_005fmaterial-1}%


\subsection*{shadow\+\_\+caster\+\_\+material}

When using \hyperlink{_shadows_Texture_002dbased-Shadows}{Texture-\/based Shadows} you can specify an alternate material to use when rendering the object using this material into the shadow texture. This is like a more advanced version of using shadow\+\_\+caster\+\_\+vertex\+\_\+program, however note that for the moment you are expected to render the shadow in one pass, i.\+e. only the first pass is respected.

\label{_shadow_005freceiver_005fmaterial}%
\label{_shadow_005freceiver_005fmaterial-1}%


\subsection*{shadow\+\_\+receiver\+\_\+material}

When using \hyperlink{_shadows_Texture_002dbased-Shadows}{Texture-\/based Shadows} you can specify an alternate material to use when performing the receiver shadow pass. Note that this explicit ’receiver’ pass is only done when you’re {\bfseries not} using \hyperlink{_shadows_Integrated-Texture-Shadows}{Integrated Texture Shadows} -\/ i.\+e. the shadow rendering is done separately (either as a modulative pass, or a masked light pass). This is like a more advanced version of using shadow\+\_\+receiver\+\_\+vertex\+\_\+program and shadow\+\_\+receiver\+\_\+fragment\+\_\+program, however note that for the moment you are expected to render the shadow in one pass, i.\+e. only the first pass is respected.

\label{_gpu_005fvendor_005frule}%
\label{_gpu_005fdevice_005frule}%
\label{_gpu_005fvendor_005frule-and-gpu_005fdevice_005frule}%


\subsection*{gpu\+\_\+vendor\+\_\+rule and gpu\+\_\+device\+\_\+rule}

Although \hyperlink{namespace_ogre}{Ogre} does a good job of detecting the capabilities of graphics cards and setting the supportability of techniques from that, occasionally card-\/specific behaviour exists which is not necessarily detectable and you may want to ensure that your materials go down a particular path to either use or avoid that behaviour. This is what these rules are for -\/ you can specify matching rules so that a technique will be considered supportable only on cards from a particular vendor, or which match a device name pattern, or will be considered supported only if they {\bfseries don’t} fulfil such matches. The format of the rules are as follows\+:

\begin{DoxyParagraph}{}
gpu\+\_\+vendor\+\_\+rule $<$include$\vert$exclude$>$ $<$vendor\+\_\+name$>$~\newline
 gpu\+\_\+device\+\_\+rule $<$include$\vert$exclude$>$ $<$device\+\_\+pattern$>$ \mbox{[}case\+\_\+sensitive\mbox{]}
\end{DoxyParagraph}
An ’include’ rule means that the technique will only be supported if one of the include rules is matched (if no include rules are provided, anything will pass). An ’exclude’ rules means that the technique is considered unsupported if any of the exclude rules are matched. You can provide as many rules as you like, although $<$vendor\+\_\+name$>$ and $<$device\+\_\+pattern$>$ must obviously be unique. The valid list of $<$vendor\+\_\+name$>$ values is currently ’nvidia’, ’ati’, ’intel’, ’s3’, ’matrox’ and ’3dlabs’. $<$device\+\_\+pattern$>$ can be any string, and you can use wildcards (’$\ast$’) if you need to match variants. Here’s an example\+:

\begin{DoxyParagraph}{}
gpu\+\_\+vendor\+\_\+rule include nvidia~\newline
 gpu\+\_\+vendor\+\_\+rule include intel~\newline
 gpu\+\_\+device\+\_\+rule exclude $\ast$950$\ast$
\end{DoxyParagraph}
These rules, if all included in one technique, will mean that the technique will only be considered supported on graphics cards made by N\+V\+I\+D\+IA and Intel, and so long as the device name doesn’t have ’950’ in it.

Note that these rules can only mark a technique ’unsupported’ when it would otherwise be considered ’supported’ judging by the hardware capabilities. Even if a technique passes these rules, it is still subject to the usual hardware support tests.\hypertarget{_material-_scripts_Passes}{}\subsubsection{Passes}\label{_material-_scripts_Passes}
A pass is a single render of the geometry in question; a single call to the rendering A\+PI with a certain set of rendering properties. A technique can have between one and 16 passes, although clearly the more passes you use, the more expensive the technique will be to render.

To help clearly identify what each pass is used for, the pass can be named but its optional. Passes not named within the script will take on a name that is the pass index number. For example\+: the first pass in a technique is index 0 so its name would be \char`\"{}0\char`\"{} if it was not given a name in the script. The pass name must be unique within the technique or else the final pass is the resulting merge of all passes with the same name in the technique. A warning message is posted in the Ogre.\+log if this occurs. Named passes can help when inheriting a material and modifying an existing pass\+: (See \hyperlink{_scripts_Script-Inheritance}{Script Inheritance})

Passes have a set of global attributes (described below) and optionally
\begin{DoxyItemize}
\item zero or more nested texture\+\_\+unit entries (See \hyperlink{_material-_scripts_Texture-Units}{Texture Units})
\item references to shader programs (See \hyperlink{_high-level-_programs_Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass}{Using G\+PU Programs in a Pass})
\item additional instructions for the R\+T\+SS (See \hyperlink{rtss_rtss_custom_mat}{Customizing the R\+T\+SS using Material Scripts})
\end{DoxyItemize}

Here are the attributes you can use in a ’pass’ section of a .material script\+:


\begin{DoxyItemize}
\item \href{#ambient}{\tt ambient}
\item \href{#diffuse}{\tt diffuse}
\item \href{#specular}{\tt specular}
\item \href{#emissive}{\tt emissive}
\item \href{#scene_005fblend}{\tt scene\+\_\+blend}
\item \href{#separate_005fscene_005fblend}{\tt separate\+\_\+scene\+\_\+blend}
\item \href{#scene_005fblend_005fop}{\tt scene\+\_\+blend\+\_\+op}
\item \href{#separate_005fscene_005fblend_005fop}{\tt separate\+\_\+scene\+\_\+blend\+\_\+op}
\item \href{#depth_005fcheck}{\tt depth\+\_\+check}
\item \href{#depth_005fwrite}{\tt depth\+\_\+write}
\item \href{#depth_005ffunc}{\tt depth\+\_\+func}
\item \href{#depth_005fbias}{\tt depth\+\_\+bias}
\item \href{#iteration_005fdepth_005fbias}{\tt iteration\+\_\+depth\+\_\+bias}
\item \href{#alpha_005frejection}{\tt alpha\+\_\+rejection}
\item \href{#alpha_005fto_005fcoverage}{\tt alpha\+\_\+to\+\_\+coverage}
\item \href{#light_005fscissor}{\tt light\+\_\+scissor}
\item \href{#light_005fclip_005fplanes}{\tt light\+\_\+clip\+\_\+planes}
\item \href{#illumination_005fstage}{\tt illumination\+\_\+stage}
\item \href{#transparent_005fsorting}{\tt transparent\+\_\+sorting}
\item \href{#normalise_005fnormals}{\tt normalise\+\_\+normals}
\item \href{#cull_005fhardware}{\tt cull\+\_\+hardware}
\item \href{#cull_005fsoftware}{\tt cull\+\_\+software}
\item \href{#lighting}{\tt lighting}
\item \href{#shading}{\tt shading}
\item \href{#polygon_005fmode}{\tt polygon\+\_\+mode}
\item \href{#polygon_005fmode_005foverrideable}{\tt polygon\+\_\+mode\+\_\+overrideable}
\item \href{#fog_005foverride}{\tt fog\+\_\+override}
\item \href{#colour_005fwrite}{\tt colour\+\_\+write}
\item \href{#max_005flights}{\tt max\+\_\+lights}
\item \href{#start_005flight}{\tt start\+\_\+light}
\item \href{#iteration}{\tt iteration}
\item \href{#point_005fsize}{\tt point\+\_\+size}
\item \href{#point_005fsprites}{\tt point\+\_\+sprites}
\item \href{#point_005fsize_005fattenuation}{\tt point\+\_\+size\+\_\+attenuation}
\item \href{#point_005fsize_005fmin}{\tt point\+\_\+size\+\_\+min}
\item \href{#point_005fsize_005fmax}{\tt point\+\_\+size\+\_\+max}
\item \href{#line_width}{\tt line\+\_\+width}
\end{DoxyItemize}

\label{_Attribute-Descriptions}%


\section*{Attribute Descriptions}

\label{_ambient}%
\label{_ambient-1}%


\subsection*{ambient}

Sets the ambient colour reflectance properties of this pass.

\begin{DoxyParagraph}{}
Format\+: ambient ($<$red$>$ $<$green$>$ $<$blue$>$ \mbox{[}$<$alpha$>$\mbox{]}$\vert$ vertexcolour)~\newline
 NB valid colour values are between 0.\+0 and 1.\+0.
\end{DoxyParagraph}
This property determines how much ambient light (directionless global light) is reflected. The default is full white, meaning objects are completely globally illuminated. Reduce this if you want to see diffuse or specular light effects, or change the blend of colours to make the object have a base colour other than white.

It is also possible to make the ambient reflectance track the vertex colour as defined in the mesh instead of the colour values. \begin{DoxyNote}{Note}
This setting has no effect if dynamic lighting is disabled (see \hyperlink{class_ogre_1_1_pass_a6285f13a06eb7f00b83ea2754e434623}{Ogre\+::\+Pass\+::set\+Lighting\+Enabled}), or, if any texture layer has a \hyperlink{group___materials_ggabcbb38d1ac195e4be401f85b7ab0da8fa870cf51ff1ccd919cf710bcb3b4e6432}{Ogre\+::\+L\+B\+O\+\_\+\+R\+E\+P\+L\+A\+CE} attribute. 

When using shader programs, you have to explicitely forward this property in the \hyperlink{_high-level-_programs_Program-Parameter-Specification}{Parameter specification}
\end{DoxyNote}
\begin{DoxyParagraph}{}
Example\+: ambient 0.\+0 0.\+8 0.\+0 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: ambient 1.\+0 1.\+0 1.\+0 1.\+0
\end{DoxyParagraph}
\label{_diffuse}%
\label{_diffuse-1}%


\subsection*{diffuse}

Sets the diffuse colour reflectance properties of this pass. \begin{DoxyParagraph}{}
Format\+: diffuse ($<$red$>$ $<$green$>$ $<$blue$>$ \mbox{[}$<$alpha$>$\mbox{]}$\vert$ vertexcolour)~\newline
 NB valid colour values are between 0.\+0 and 1.\+0.
\end{DoxyParagraph}
This property determines how much diffuse light (light from instances of the Light class in the scene) is reflected. The default is full white, meaning objects reflect the maximum white light they can from Light objects.

It is also possible to make the diffuse reflectance track the vertex colour as defined in the mesh instead of the colour values. \begin{DoxyNote}{Note}
This setting has no effect if dynamic lighting is disabled (see \hyperlink{class_ogre_1_1_pass_a6285f13a06eb7f00b83ea2754e434623}{Ogre\+::\+Pass\+::set\+Lighting\+Enabled}), or, if any texture layer has a \hyperlink{group___materials_ggabcbb38d1ac195e4be401f85b7ab0da8fa870cf51ff1ccd919cf710bcb3b4e6432}{Ogre\+::\+L\+B\+O\+\_\+\+R\+E\+P\+L\+A\+CE} attribute. 

When using shader programs, you have to explicitely forward this property in the \hyperlink{_high-level-_programs_Program-Parameter-Specification}{Parameter specification}
\end{DoxyNote}
\begin{DoxyParagraph}{}
Example\+: diffuse 1.\+0 0.\+5 0.\+5 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: diffuse 1.\+0 1.\+0 1.\+0 1.\+0
\end{DoxyParagraph}
\label{_specular}%
\label{_specular-1}%


\subsection*{specular}

Sets the specular colour reflectance properties of this pass. \begin{DoxyParagraph}{}
Format\+: specular ($<$red$>$ $<$green$>$ $<$blue$>$ \mbox{[}$<$alpha$>$\mbox{]}$\vert$ vertexcolour) $<$shininess$>$~\newline
 NB valid colour values are between 0.\+0 and 1.\+0. Shininess can be any value greater than 0.
\end{DoxyParagraph}
This property determines how much specular light (highlights from instances of the Light class in the scene) is reflected. The default is to reflect no specular light. The colour of the specular highlights is determined by the colour parameters, and the size of the highlights by the separate shininess parameter. It is also possible to make the specular reflectance track the vertex colour as defined in the mesh instead of the colour values.

The higher the value of the shininess parameter, the sharper the highlight i.\+e. the radius is smaller. Beware of using shininess values in the range of 0 to 1 since this causes the the specular colour to be applied to the whole surface that has the material applied to it. When the viewing angle to the surface changes, ugly flickering will also occur when shininess is in the range of 0 to 1. Shininess values between 1 and 128 work best in both DirectX and Open\+GL renderers. \begin{DoxyNote}{Note}
This setting has no effect if dynamic lighting is disabled (see \hyperlink{class_ogre_1_1_pass_a6285f13a06eb7f00b83ea2754e434623}{Ogre\+::\+Pass\+::set\+Lighting\+Enabled}), or, if any texture layer has a \hyperlink{group___materials_ggabcbb38d1ac195e4be401f85b7ab0da8fa870cf51ff1ccd919cf710bcb3b4e6432}{Ogre\+::\+L\+B\+O\+\_\+\+R\+E\+P\+L\+A\+CE} attribute. 

When using shader programs, you have to explicitely forward this property in the \hyperlink{_high-level-_programs_Program-Parameter-Specification}{Parameter specification}
\end{DoxyNote}
\begin{DoxyParagraph}{}
Example\+: specular 1.\+0 1.\+0 1.\+0 12.\+5
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: specular 0.\+0 0.\+0 0.\+0 0.\+0 0.\+0
\end{DoxyParagraph}
\label{_emissive}%
\label{_emissive-1}%


\subsection*{emissive}

Sets the amount of self-\/illumination an object has.

\begin{DoxyParagraph}{}
Format\+: emissive ($<$red$>$ $<$green$>$ $<$blue$>$ \mbox{[}$<$alpha$>$\mbox{]}$\vert$ vertexcolour)~\newline
 NB valid colour values are between 0.\+0 and 1.\+0.
\end{DoxyParagraph}
Unlike the name suggests, this object doesn’t act as a light source for other objects in the scene (if you want it to, you have to create a light which is centered on the object). If an object is self-\/illuminating, it does not need external sources to light it, ambient or otherwise. It\textquotesingle{}s like the object has it\textquotesingle{}s own personal ambient light. This property is rarely useful since you can already specify per-\/pass ambient light, but is here for completeness.

It is also possible to make the emissive reflectance track the vertex colour as defined in the mesh instead of the colour values. \begin{DoxyNote}{Note}
This setting has no effect if dynamic lighting is disabled (see \hyperlink{class_ogre_1_1_pass_a6285f13a06eb7f00b83ea2754e434623}{Ogre\+::\+Pass\+::set\+Lighting\+Enabled}), or, if any texture layer has a \hyperlink{group___materials_ggabcbb38d1ac195e4be401f85b7ab0da8fa870cf51ff1ccd919cf710bcb3b4e6432}{Ogre\+::\+L\+B\+O\+\_\+\+R\+E\+P\+L\+A\+CE} attribute. 

When using shader programs, you have to explicitely forward this property in the \hyperlink{_high-level-_programs_Program-Parameter-Specification}{Parameter specification}
\end{DoxyNote}
\begin{DoxyParagraph}{}
Example\+: emissive 1.\+0 0.\+0 0.\+0 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: emissive 0.\+0 0.\+0 0.\+0 0.\+0
\end{DoxyParagraph}
\label{_scene_005fblend}%
\label{_scene_005fblend-1}%


\subsection*{scene\+\_\+blend}

Sets the kind of blending this pass has with the existing contents of the scene.

Whereas the texture blending operations seen in the texture\+\_\+unit entries are concerned with blending between texture layers, this blending is about combining the output of this pass as a whole with the existing contents of the rendering target. This blending therefore allows object transparency and other special effects.

There are 2 formats, one using predefined blend types, the other allowing a roll-\/your-\/own approach using source and destination factors. \begin{DoxyParagraph}{}
Format1\+: scene\+\_\+blend $<$blend\+\_\+type$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: scene\+\_\+blend add
\end{DoxyParagraph}
This is the simpler form, where the most commonly used blending modes are enumerated using a single parameter.


\begin{DoxyParams}{Parameters}
{\em blend\+\_\+type} & 
\begin{DoxyDescription}
\item[add ]The colour of the rendering output is added to the scene. Good for explosions, flares, lights, ghosts etc.

Equivalent to ’scene\+\_\+blend one one’. 
\item[modulate ]The colour of the rendering output is multiplied with the scene contents. Generally colours and darkens the scene, good for smoked glass, semi-\/transparent objects etc.

Equivalent to ’scene\+\_\+blend dest\+\_\+colour zero’. 
\item[colour\+\_\+blend ]Colour the scene based on the brightness of the input colours, but don’t darken.

Equivalent to ’scene\+\_\+blend src\+\_\+colour one\+\_\+minus\+\_\+src\+\_\+colour’ 
\item[alpha\+\_\+blend ]The alpha value of the rendering output is used as a mask.

Equivalent to ’scene\+\_\+blend src\+\_\+alpha one\+\_\+minus\+\_\+src\+\_\+alpha’ 
\end{DoxyDescription}\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Format2\+: scene\+\_\+blend $<$source\+Factor$>$ $<$dest\+Factor$>$
\end{DoxyParagraph}
This version of the method allows complete control over the blending operation, by specifying the source and destination blending factors. The result of the blending operation is\+:

\$\$final = (pass\+Output $\ast$ source\+Factor) + (frame\+Buffer $\ast$ dest\+Factor)\$\$

Each of the factors is specified as one of a number of options, as specified in the \hyperlink{group___materials_ga41c76d419d6c9c205a6c1d3b42872213}{Ogre\+::\+Scene\+Blend\+Factor} enumerated type. 
\begin{DoxyParams}{Parameters}
{\em source\+Factor} & The source factor in the above calculation, i.\+e. multiplied by the output of the Pass. \\
\hline
{\em dest\+Factor} & The destination factor in the above calculation, i.\+e. multiplied by the Frame Buffer contents.\\
\hline
\end{DoxyParams}
Valid values for both parameters are one of \hyperlink{group___materials_ga41c76d419d6c9c205a6c1d3b42872213}{Ogre\+::\+Scene\+Blend\+Factor} without the {\ttfamily S\+B\+F\+\_\+} prefix. E.\+g. {\ttfamily S\+B\+F\+\_\+\+D\+E\+S\+T\+\_\+\+C\+O\+L\+O\+UR} becomes {\ttfamily dest\+\_\+colour}.

\begin{DoxyParagraph}{}
Example\+: scene\+\_\+blend one one\+\_\+minus\+\_\+dest\+\_\+alpha
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: scene\+\_\+blend one zero (opaque)
\end{DoxyParagraph}
Also see \href{#separate_005fscene_005fblend}{\tt separate\+\_\+scene\+\_\+blend}.

\label{_separate_005fscene_005fblend}%
\label{_separate_005fscene_005fblend-1}%


\subsection*{separate\+\_\+scene\+\_\+blend}

This option operates in exactly the same way as \href{#scene_005fblend}{\tt scene\+\_\+blend}, except that it allows you to specify the operations to perform between the rendered pixel and the frame buffer separately for colour and alpha components. By nature this option is only useful when rendering to targets which have an alpha channel which you’ll use for later processing, such as a render texture. \begin{DoxyParagraph}{}
Format1\+: separate\+\_\+scene\+\_\+blend $<$simple\+\_\+colour\+\_\+blend$>$ $<$simple\+\_\+alpha\+\_\+blend$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: separate\+\_\+scene\+\_\+blend add modulate
\end{DoxyParagraph}
This example would add colour components but multiply alpha components. The blend modes available are as in \href{#scene_005fblend}{\tt scene\+\_\+blend}. The more advanced form is also available\+: \begin{DoxyParagraph}{}
Format2\+: separate\+\_\+scene\+\_\+blend $<$colour\+\_\+src\+\_\+factor$>$ $<$colour\+\_\+dest\+\_\+factor$>$ $<$alpha\+\_\+src\+\_\+factor$>$ $<$alpha\+\_\+dest\+\_\+factor$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: separate\+\_\+scene\+\_\+blend one one\+\_\+minus\+\_\+dest\+\_\+alpha one one
\end{DoxyParagraph}
Again the options available in the second format are the same as those in the second format of \href{#scene_005fblend}{\tt scene\+\_\+blend}.

\label{_scene_005fblend_005fop}%
\label{_scene_005fblend_005fop-1}%


\subsection*{scene\+\_\+blend\+\_\+op}

This directive changes the operation which is applied between the two components of the scene blending equation

\begin{DoxyParagraph}{}
Format\+: scene\+\_\+blend\+\_\+op $<$op$>$
\end{DoxyParagraph}
By default this operation is \hyperlink{group___materials_ggaa7a12a72231aedf6e33d58aafc11214aa188aee58620b3275f1a45c7c80df4bc7}{Ogre\+::\+S\+B\+O\+\_\+\+A\+DD}, which creates this equation

\$\$final = (pass\+Output $\ast$ source\+Factor) + (frame\+Buffer $\ast$ dest\+Factor)\$\$

By setting this to something other than S\+B\+O\+\_\+\+A\+DD you can change the operation to achieve a different effect. 
\begin{DoxyParams}{Parameters}
{\em op} & The blending operation mode to use for this pass You may change this to ’add’, ’subtract’, ’reverse\+\_\+subtract’, ’min’ or ’max’.\\
\hline
\end{DoxyParams}
\label{_separate_005fscene_005fblend_005fop}%
\label{_separate_005fscene_005fblend_005fop-1}%


\subsection*{separate\+\_\+scene\+\_\+blend\+\_\+op}

This directive is as scene\+\_\+blend\+\_\+op, except that you can set the operation for colour and alpha separately. \begin{DoxyParagraph}{}
Format\+: separate\+\_\+scene\+\_\+blend\+\_\+op $<$colour\+Op$>$ $<$alpha\+Op$>$ Default\+: separate\+\_\+scene\+\_\+blend\+\_\+op add add
\end{DoxyParagraph}
\label{_depth_005fcheck}%
\label{_depth_005fcheck-1}%


\subsection*{depth\+\_\+check}

Sets whether or not this pass renders with depth-\/buffer checking on or not. \begin{DoxyParagraph}{}
Format\+: depth\+\_\+check $<$on$\vert$off$>$
\end{DoxyParagraph}
If depth-\/buffer checking is on, whenever a pixel is about to be written to the frame buffer the depth buffer is checked to see if the pixel is in front of all other pixels written at that point. If not, the pixel is not written.

If depth checking is off, pixels are written no matter what has been rendered before. Also see set\+Depth\+Function for more advanced depth check configuration. \begin{DoxySeeAlso}{See also}
\hyperlink{group___general_ga0212b4eb264f207d84c1df9425208c7a}{Ogre\+::\+Compare\+Function}
\end{DoxySeeAlso}
Default\+: depth\+\_\+check on

\label{_depth_005fwrite}%
\label{_depth_005fwrite-1}%


\subsection*{depth\+\_\+write}

Sets whether or not this pass renders with depth-\/buffer writing on or not.

\begin{DoxyParagraph}{}
Format\+: depth\+\_\+write $<$on$\vert$off$>$
\end{DoxyParagraph}
If depth-\/buffer writing is on, whenever a pixel is written to the frame buffer the depth buffer is updated with the depth value of that new pixel, thus affecting future rendering operations if future pixels are behind this one.

If depth writing is off, pixels are written without updating the depth buffer Depth writing should normally be on but can be turned off when rendering static backgrounds or when rendering a collection of transparent objects at the end of a scene so that they overlap each other correctly.

\begin{DoxyParagraph}{}
Default\+: depth\+\_\+write on~\newline

\end{DoxyParagraph}
\label{_depth_005ffunc}%
\label{_depth_005ffunc-1}%


\subsection*{depth\+\_\+func}

Sets the function used to compare depth values when depth checking is on. \begin{DoxyParagraph}{}
Format\+: depth\+\_\+func $<$func$>$
\end{DoxyParagraph}
If depth checking is enabled (see set\+Depth\+Check\+Enabled) a comparison occurs between the depth value of the pixel to be written and the current contents of the buffer. This comparison is normally \hyperlink{group___general_gga0212b4eb264f207d84c1df9425208c7aa2272d0faefcf5a2e08bbf7d232d7520b}{Ogre\+::\+C\+M\+P\+F\+\_\+\+L\+E\+S\+S\+\_\+\+E\+Q\+U\+AL}.


\begin{DoxyParams}{Parameters}
{\em func} & one of \hyperlink{group___general_ga0212b4eb264f207d84c1df9425208c7a}{Ogre\+::\+Compare\+Function} without the {\ttfamily C\+M\+P\+F\+\_\+} prefix. E.\+g. {\ttfamily C\+M\+P\+F\+\_\+\+L\+E\+S\+S\+\_\+\+E\+Q\+U\+AL} becomes {\ttfamily less\+\_\+equal}.\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Default\+: depth\+\_\+func less\+\_\+equal
\end{DoxyParagraph}
\label{_depth_005fbias}%
\label{_depth_005fbias-1}%


\subsection*{depth\+\_\+bias}

Sets the bias applied to the depth value of this pass. \begin{DoxyParagraph}{}
Format\+: depth\+\_\+bias $<$constant\+Bias$>$ \mbox{[}$<$slope\+Scale\+Bias$>$\mbox{]}
\end{DoxyParagraph}
When polygons are coplanar, you can get problems with \textquotesingle{}depth fighting\textquotesingle{} where the pixels from the two polys compete for the same screen pixel. This is particularly a problem for decals (polys attached to another surface to represent details such as bulletholes etc.).

A way to combat this problem is to use a depth bias to adjust the depth buffer value used for the decal such that it is slightly higher than the true value, ensuring that the decal appears on top. There are two aspects to the biasing, a constant bias value and a slope-\/relative biasing value, which varies according to the maximum depth slope relative to the camera, ie\+:

\$\$final\+Bias = max\+Slope $\ast$ slope\+Scale\+Bias + constant\+Bias\$\$

Slope scale biasing is relative to the angle of the polygon to the camera, which makes for a more appropriate bias value, but this is ignored on some older hardware. Constant biasing is expressed as a factor of the minimum depth value, so a value of 1 will nudge the depth by one ’notch’ if you will. 
\begin{DoxyParams}{Parameters}
{\em constant\+Bias} & The constant bias value \\
\hline
{\em slope\+Scale\+Bias} & The slope-\/relative bias value\\
\hline
\end{DoxyParams}
Also see \href{#iteration_005fdepth_005fbias}{\tt iteration\+\_\+depth\+\_\+bias}

\label{_iteration_005fdepth_005fbias}%
\label{_iteration_005fdepth_005fbias-1}%


\subsection*{iteration\+\_\+depth\+\_\+bias}

Sets an additional bias derived from the number of times a given pass has been iterated. Operates just like \href{#depth_005fbias}{\tt depth\+\_\+bias} except that it applies an additional bias factor to the base depth\+\_\+bias value, multiplying the provided value by the number of times this pass has been iterated before, through one of the \href{#iteration}{\tt iteration} variants. So the first time the pass will get the depth\+\_\+bias value, the second time it will get depth\+\_\+bias + iteration\+\_\+depth\+\_\+bias, the third time it will get depth\+\_\+bias + iteration\+\_\+depth\+\_\+bias $\ast$ 2, and so on. The default is zero. \begin{DoxyParagraph}{}
Format\+: iteration\+\_\+depth\+\_\+bias $<$bias\+\_\+per\+\_\+iteration$>$
\end{DoxyParagraph}
\label{_alpha_005frejection}%
\label{_alpha_005frejection-1}%


\subsection*{alpha\+\_\+rejection}

Sets the way the pass will have use alpha to totally reject pixels from the pipeline. \begin{DoxyParagraph}{}
Format\+: alpha\+\_\+rejection $<$function$>$ $<$value$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: alpha\+\_\+rejection greater\+\_\+equal 128
\end{DoxyParagraph}
The function parameter can be any of the options listed in the material depth\+\_\+function attribute. The value parameter can theoretically be any value between 0 and 255, but is best limited to 0 or 128 for hardware compatibility. \begin{DoxyParagraph}{}
Default\+: alpha\+\_\+rejection always\+\_\+pass
\end{DoxyParagraph}
\label{_alpha_005fto_005fcoverage}%
\label{_alpha_005fto_005fcoverage-1}%


\subsection*{alpha\+\_\+to\+\_\+coverage}

Sets whether this pass will use ’alpha to coverage’,

\begin{DoxyParagraph}{}
Format\+: alpha\+\_\+to\+\_\+coverage $<$on$\vert$off$>$
\end{DoxyParagraph}
Alpha to coverage performs multisampling on the edges of alpha-\/rejected textures to produce a smoother result. It is only supported when multisampling is already enabled on the render target, and when the hardware supports alpha to coverage (see Render\+System\+Capabilities). The common use for alpha to coverage is foliage rendering and chain-\/link fence style textures.

\begin{DoxyParagraph}{}
Default\+: alpha\+\_\+to\+\_\+coverage off \label{_light_005fscissor}%

\end{DoxyParagraph}
\label{_light_005fscissor-1}%


\subsection*{light\+\_\+scissor}

Sets whether when rendering this pass, rendering will be limited to a screen-\/space scissor rectangle representing the coverage of the light(s) being used in this pass. \begin{DoxyParagraph}{}
Format\+: light\+\_\+scissor $<$on$\vert$off$>$ Default\+: light\+\_\+scissor off
\end{DoxyParagraph}
In order to cut down on fillrate when you have a number of fixed-\/range lights in the scene, you can enable this option to request that during rendering, only the region of the screen which is covered by the lights is rendered. This region is the screen-\/space rectangle covering the union of the spheres making up the light ranges. Directional lights are ignored for this.

This is only likely to be useful for multipass additive lighting algorithms, where the scene has already been \textquotesingle{}seeded\textquotesingle{} with an ambient pass and this pass is just adding light in affected areas.

When using \hyperlink{group___general_gga79dcd426d291c31072c1ad6f183715d6af6e22c7a699e9d05015cecff7b68c52a}{Ogre\+::\+S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+S\+T\+E\+N\+C\+I\+L\+\_\+\+A\+D\+D\+I\+T\+I\+VE} or \hyperlink{group___general_gga79dcd426d291c31072c1ad6f183715d6a8a2b43e30e6d8d590e6853e4f46b8103}{Ogre\+::\+S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+A\+D\+D\+I\+T\+I\+VE}, this option is implicitly used for all per-\/light passes and does not need to be specified. If you are not using shadows or are using a modulative or an integrated shadow technique then this could be useful.

\begin{DoxySeeAlso}{See also}
\hyperlink{_shadows_Integrated-Texture-Shadows}{Integrated Texture Shadows}
\end{DoxySeeAlso}
\label{_light_005fclip_005fplanes}%
\label{_light_005fclip_005fplanes-1}%


\subsection*{light\+\_\+clip\+\_\+planes}

Sets whether when rendering this pass, triangle setup will be limited to clipping volume covered by the light. \begin{DoxyParagraph}{}
Format\+: light\+\_\+clip\+\_\+planes $<$on$\vert$off$>$ Default\+: light\+\_\+clip\+\_\+planes off
\end{DoxyParagraph}
This option will only function if there is a single non-\/directional light being used in this pass. If there is more than one light, or only directional lights, then no clipping will occur. If there are no lights at all then the objects won’t be rendered at all.

In order to cut down on the geometry set up to render this pass when you have a single fixed-\/range light being rendered through it, you can enable this option to request that during triangle setup, clip planes are defined to bound the range of the light. In the case of a point light these planes form a cube, and in the case of a spotlight they form a pyramid. Directional lights are never clipped.

This option is only likely to be useful for multipass additive lighting algorithms, where the scene has already been \textquotesingle{}seeded\textquotesingle{} with an ambient pass and this pass is just adding light in affected areas. In addition, it will only be honoured if there is exactly one non-\/directional light being used in this pass. Also, these clip planes override any user clip planes set on Camera.

When using \hyperlink{group___general_gga79dcd426d291c31072c1ad6f183715d6af6e22c7a699e9d05015cecff7b68c52a}{Ogre\+::\+S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+S\+T\+E\+N\+C\+I\+L\+\_\+\+A\+D\+D\+I\+T\+I\+VE} or \hyperlink{group___general_gga79dcd426d291c31072c1ad6f183715d6a8a2b43e30e6d8d590e6853e4f46b8103}{Ogre\+::\+S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+A\+D\+D\+I\+T\+I\+VE}, this option is automatically used for all per-\/light passes if you enable \hyperlink{class_ogre_1_1_scene_manager_a40f296de8599657b70b7072921cbaa16}{Ogre\+::\+Scene\+Manager\+::set\+Shadow\+Use\+Light\+Clip\+Planes} and does not need to be specified. It is disabled by default since clip planes have a cost of their own which may not always exceed the benefits they give you. Generally the smaller your lights are the more chance you’ll see a benefit rather than a penalty from clipping.

\begin{DoxyNote}{Note}
A specific note about Open\+GL\+: user clip planes are completely ignored when you use an A\+RB vertex program. This means light clip planes won’t help much if you use A\+RB vertex programs on GL, although O\+G\+RE will perform some optimisation of its own, in that if it sees that the clip volume is completely off-\/screen, it won’t perform a render at all. When using G\+L\+SL, user clipping can be used but you have to use gl\+\_\+\+Clip\+Vertex in your shader, see the G\+L\+SL documentation for more information. In Direct3D user clip planes are always respected.
\end{DoxyNote}
\begin{DoxySeeAlso}{See also}
\hyperlink{_shadows_Integrated-Texture-Shadows}{Integrated Texture Shadows}
\end{DoxySeeAlso}
\label{_illumination_005fstage}%
\label{_illumination_005fstage-1}%


\subsection*{illumination\+\_\+stage}

When using an additive lighting mode (\hyperlink{group___general_gga79dcd426d291c31072c1ad6f183715d6af6e22c7a699e9d05015cecff7b68c52a}{Ogre\+::\+S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+S\+T\+E\+N\+C\+I\+L\+\_\+\+A\+D\+D\+I\+T\+I\+VE} or \hyperlink{group___general_gga79dcd426d291c31072c1ad6f183715d6a8a2b43e30e6d8d590e6853e4f46b8103}{Ogre\+::\+S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+A\+D\+D\+I\+T\+I\+VE}), the scene is rendered in 3 discrete stages, ambient (or pre-\/lighting), per-\/light (once per light, with shadowing) and decal (or post-\/lighting). Usually O\+G\+RE figures out how to categorise your passes automatically, but there are some effects you cannot achieve without manually controlling the illumination. For example specular effects are muted by the typical sequence because all textures are saved until the \hyperlink{group___materials_gga12a2bc4c75c439630241aa279089acb4a55b9a19dea33fdf42c614c99c136a52e}{Ogre\+::\+I\+S\+\_\+\+D\+E\+C\+AL} stage which mutes the specular effect. Instead, you could do texturing within the per-\/light stage if it\textquotesingle{}s possible for your material and thus add the specular on after the decal texturing, and have no post-\/light rendering.

If you assign an illumination stage to a pass you have to assign it to all passes in the technique otherwise it will be ignored. Also note that whilst you can have more than one pass in each group, they cannot alternate, ie all ambient passes will be before all per-\/light passes, which will also be before all decal passes. Within their categories the passes will retain their ordering though.

\begin{DoxyParagraph}{}
Format\+: illumination\+\_\+stage $<$ambient$\vert$per\+\_\+light$\vert$decal$>$ Default\+: none (autodetect)
\end{DoxyParagraph}
\label{_normalise_005fnormals}%
\label{_normalise_005fnormals-1}%


\subsection*{normalise\+\_\+normals}

Sets whether or not this pass renders with all vertex normals being automatically re-\/normalised.~\newline
 \begin{DoxyParagraph}{}
Format\+: normalise\+\_\+normals $<$on$\vert$off$>$
\end{DoxyParagraph}
This option can be used to prevent lighting variations when scaling an object -\/ normally because this scaling is hardware based, the normals get scaled too which causes lighting to become inconsistent. By default the Scene\+Manager detects scaled objects and does this for you, but this has an overhead so you might want to turn that off through Ogre\+::\+Scene\+Manager\+::set\+Normalise\+Normals\+On\+Scale(false) and only do it per-\/\+Pass when you need to.

\begin{DoxyParagraph}{}
Default\+: normalise\+\_\+normals off~\newline

\end{DoxyParagraph}
\label{_transparent_005fsorting}%
\label{_transparent_005fsorting-1}%


\subsection*{transparent\+\_\+sorting}

Sets if transparent textures should be sorted by depth or not. \begin{DoxyParagraph}{}
Format\+: transparent\+\_\+sorting $<$on$\vert$off$\vert$force$>$
\end{DoxyParagraph}
By default all transparent materials are sorted such that renderables furthest away from the camera are rendered first. This is usually the desired behaviour but in certain cases this depth sorting may be unnecessary and undesirable. If for example it is necessary to ensure the rendering order does not change from one frame to the next. In this case you could set the value to ’off’ to prevent sorting.

You can also use the keyword ’force’ to force transparent sorting on, regardless of other circumstances. Usually sorting is only used when the pass is also transparent, and has a depth write or read which indicates it cannot reliably render without sorting. By using ’force’, you tell O\+G\+RE to sort this pass no matter what other circumstances are present. \begin{DoxyParagraph}{}
Default\+: transparent\+\_\+sorting on
\end{DoxyParagraph}
\label{_cull_005fhardware}%
\label{_cull_005fhardware-1}%


\subsection*{cull\+\_\+hardware}

Sets the hardware culling mode for this pass. \begin{DoxyParagraph}{}
Format\+: cull\+\_\+hardware $<$clockwise$\vert$anticlockwise$\vert$none$>$
\end{DoxyParagraph}
A typical way for the rendering engine to cull triangles is based on the \textquotesingle{}vertex winding\textquotesingle{} of triangles. Vertex winding refers to the direction in which the vertices are passed or indexed to in the rendering operation as viewed from the camera, and will wither be clockwise or anticlockwise (that\textquotesingle{}s \textquotesingle{}counterclockwise\textquotesingle{} for you Americans out there ;) The default is \hyperlink{group___general_ggac173244ed7d950d0acd726e4f323ecdba50170ef4a0a12b9fc6bf0c53e582bdf0}{Ogre\+::\+C\+U\+L\+L\+\_\+\+C\+L\+O\+C\+K\+W\+I\+SE} i.\+e. that only triangles whose vertices are passed/indexed in anticlockwise order are rendered -\/ this is a common approach and is used in 3D studio models for example. You can alter this culling mode if you wish but it is not advised unless you know what you are doing.

You may wish to use the \hyperlink{group___general_ggac173244ed7d950d0acd726e4f323ecdba7868e61bf90df40d5e04e3a951729248}{Ogre\+::\+C\+U\+L\+L\+\_\+\+N\+O\+NE} option for mesh data that you cull yourself where the vertex winding is uncertain or for creating 2-\/sided passes.

\begin{DoxyParagraph}{}
Default\+: cull\+\_\+hardware clockwise~\newline
 NB this is the same as Open\+G\+L’s default but the opposite of Direct3\+D’s default (because \hyperlink{namespace_ogre}{Ogre} uses a right-\/handed coordinate system like Open\+GL).
\end{DoxyParagraph}
\label{_cull_005fsoftware}%
\label{_cull_005fsoftware-1}%


\subsection*{cull\+\_\+software}

Sets the software culling mode for this pass. \begin{DoxyParagraph}{}
Format\+: cull\+\_\+software $<$back$\vert$front$\vert$none$>$
\end{DoxyParagraph}
In some situations you want to use manual culling of triangles rather than sending the triangles to the hardware and letting it cull them. This setting only takes effect on Scene\+Manager\textquotesingle{}s that use it (since it is best used on large groups of planar world geometry rather than on movable geometry since this would be expensive), but if used can cull geometry before it is sent to the hardware.

In this case the culling is based on whether the ’back’ or ’front’ of the triangle is facing the camera -\/ this definition is based on the face normal (a vector which sticks out of the front side of the polygon perpendicular to the face). Since Ogre expects face normals to be on anticlockwise side of the face, \hyperlink{group___general_gga07ec94cf178172a6778223e6f70f23fcadbebf0c209be54ddb19d6097d4f7042f}{Ogre\+::\+M\+A\+N\+U\+A\+L\+\_\+\+C\+U\+L\+L\+\_\+\+B\+A\+CK} is the software equivalent of \hyperlink{group___general_ggac173244ed7d950d0acd726e4f323ecdba50170ef4a0a12b9fc6bf0c53e582bdf0}{Ogre\+::\+C\+U\+L\+L\+\_\+\+C\+L\+O\+C\+K\+W\+I\+SE} setting, which is why they are both the default. The naming is different to reflect the way the culling is done though, since most of the time face normals are pre-\/calculated and they don’t have to be the way Ogre expects -\/ you could set \hyperlink{group___general_ggac173244ed7d950d0acd726e4f323ecdba7868e61bf90df40d5e04e3a951729248}{Ogre\+::\+C\+U\+L\+L\+\_\+\+N\+O\+NE} and completely cull in software based on your own face normals, if you have the right Scene\+Manager which uses them.

\begin{DoxyParagraph}{}
Default\+: cull\+\_\+software back
\end{DoxyParagraph}
\label{_lighting}%
\label{_lighting-1}%


\subsection*{lighting}

Sets whether or not dynamic lighting is turned on for this pass or not.

\begin{DoxyParagraph}{}
Format\+: lighting $<$on$\vert$off$>$
\end{DoxyParagraph}
Turning dynamic lighting off makes any ambient, diffuse, specular, emissive and shading properties for this pass redundant. If lighting is turned off, all objects rendered using the pass will be fully lit. When lighting is turned on, objects are lit according to their vertex normals for diffuse and specular light, and globally for ambient and emissive. \begin{DoxyParagraph}{}
Default\+: lighting on
\end{DoxyParagraph}
\label{_shading}%
\label{_shading-1}%


\subsection*{shading}

Sets the kind of shading which should be used for representing dynamic lighting for this pass. \begin{DoxyParagraph}{}
Format\+: shading $<$mode$>$
\end{DoxyParagraph}
When dynamic lighting is turned on, the effect is to generate colour values at each vertex. Whether these values are interpolated across the face (and how) depends on this setting. The default shading method is \hyperlink{group___general_gga7afd4c7d428baaee13f3a0dbcae5f560a2973848ded9ca7c0f93a329e12181feb}{Ogre\+::\+S\+O\+\_\+\+G\+O\+U\+R\+A\+UD}.


\begin{DoxyParams}{Parameters}
{\em mode} & one of \hyperlink{group___general_ga7afd4c7d428baaee13f3a0dbcae5f560}{Ogre\+::\+Shade\+Options} without the {\ttfamily S\+O\+\_\+} prefix. E.\+g. {\ttfamily S\+O\+\_\+\+F\+L\+AT} becomes {\ttfamily flat}.\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Default\+: shading gouraud
\end{DoxyParagraph}
\label{_polygon_005fmode}%
\label{_polygon_005fmode-1}%


\subsection*{polygon\+\_\+mode}

Sets how polygons should be rasterised, i.\+e. whether they should be filled in, or just drawn as lines or points. The default shading method is \hyperlink{group___general_gga68866b02aa7f99e3431337511fbb3345a7e87bf8ec063f4e7bf022a7396346211}{Ogre\+::\+P\+M\+\_\+\+S\+O\+L\+ID}.

\begin{DoxyParagraph}{}
Format\+: polygon\+\_\+mode $<$solid$\vert$wireframe$\vert$points$>$
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em mode} & one of \hyperlink{group___general_ga68866b02aa7f99e3431337511fbb3345}{Ogre\+::\+Polygon\+Mode} without the {\ttfamily P\+M\+\_\+} prefix. E.\+g. {\ttfamily P\+M\+\_\+\+S\+O\+L\+ID} becomes {\ttfamily solid}.\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Default\+: polygon\+\_\+mode solid
\end{DoxyParagraph}
\label{_polygon_005fmode_005foverrideable}%
\label{_polygon_005fmode_005foverrideable-1}%


\subsection*{polygon\+\_\+mode\+\_\+overrideable}

Sets whether or not the \href{#polygon_005fmode}{\tt polygon\+\_\+mode} set on this pass can be downgraded by the camera

\begin{DoxyParagraph}{}
Format\+: polygon\+\_\+mode\+\_\+overrideable $<$override$>$
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em override} & If set to false, this pass will always be rendered at its own chosen polygon mode no matter what the camera says. The default is true.\\
\hline
\end{DoxyParams}
\label{_fog_005foverride}%
\label{_fog_005foverride-1}%


\subsection*{fog\+\_\+override}

Tells the pass whether it should override the scene fog settings, and enforce it’s own. Very useful for things that you don’t want to be affected by fog when the rest of the scene is fogged, or vice versa. Note that this only affects fixed-\/function fog -\/ the original scene fog parameters are still sent to shaders which use the fog\+\_\+params parameter binding (this allows you to turn off fixed function fog and calculate it in the shader instead; if you want to disable shader fog you can do that through shader parameters anyway). \begin{DoxyParagraph}{}
Format\+: fog\+\_\+override $<$override?$>$ \mbox{[}$<$type$>$ $<$colour$>$ $<$density$>$ $<$start$>$ $<$end$>$\mbox{]} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: fog\+\_\+override false
\end{DoxyParagraph}
If you specify ’true’ for the first parameter and you supply the rest of the parameters, you are telling the pass to use these fog settings in preference to the scene settings, whatever they might be. If you specify ’true’ but provide no further parameters, you are telling this pass to never use fogging no matter what the scene says.


\begin{DoxyParams}{Parameters}
{\em type} & {\bfseries none} = No fog, equivalent of just using ’fog\+\_\+override true’~\newline
 {\bfseries linear} = Linear fog from the $<$start$>$ and $<$end$>$ distances~\newline
 {\bfseries exp} = Fog increases exponentially from the camera (fog = 1/e$^\wedge$(distance $\ast$ density)), use $<$density$>$ param to control it~\newline
 {\bfseries exp2} = Fog increases at the square of F\+O\+G\+\_\+\+E\+XP, i.\+e. even quicker (fog = 1/e$^\wedge$(distance $\ast$ density)$^\wedge$2), use $<$density$>$ param to control it\\
\hline
{\em colour} & Sequence of 3 floating point values from 0 to 1 indicating the red, green and blue intensities\\
\hline
{\em density} & The density parameter used in the ’exp’ or ’exp2’ fog types. Not used in linear mode but param must still be there as a placeholder\\
\hline
{\em start} & The start distance from the camera of linear fog. Must still be present in other modes, even though it is not used.\\
\hline
{\em end} & The end distance from the camera of linear fog. Must still be present in other modes, even though it is not used.\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Example\+: fog\+\_\+override true exp 1 1 1 0.\+002 100 10000
\end{DoxyParagraph}
\label{_colour_005fwrite}%
\label{_colour_005fwrite-1}%


\subsection*{colour\+\_\+write}

Sets whether this pass renders with colour writing on or not. Alternatively, it can also be used to enable/disable colour writing specific channels. In the second format, the parameters are in the red, green, blue, alpha order.

\begin{DoxyParagraph}{}
Format 1\+: colour\+\_\+write $<$on$\vert$off$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Format 2\+: colour\+\_\+write $<$on$\vert$off$>$ $<$on$\vert$off$>$ $<$on$\vert$off$>$ $<$on$\vert$off$>$
\end{DoxyParagraph}
If colour writing is off no visible pixels are written to the screen during this pass. You might think this is useless, but if you render with colour writing off, and with very minimal other settings, you can use this pass to initialise the depth buffer before subsequently rendering other passes which fill in the colour data. This can give you significant performance boosts on some newer cards, especially when using complex fragment programs, because if the depth check fails then the fragment program is never run.

\begin{DoxyParagraph}{}
Default\+: colour\+\_\+write on~\newline

\end{DoxyParagraph}
\label{_colour_005fmask}%
\label{_colour_005fmask-1}%


\subsection*{start\+\_\+light}

Sets the first light which will be considered for use with this pass. \begin{DoxyParagraph}{}
Format\+: start\+\_\+light $<$number$>$
\end{DoxyParagraph}
Normally the lights passed to a pass will start from the beginning of the light list for this object. This option allows you to make this pass start from a higher light index, for example if one of your earlier passes could deal with lights 0-\/3, and this pass dealt with lights 4+. This option also has an interaction with pass iteration, in that if you choose to iterate this pass per light too, the iteration will only begin from light 4.

\begin{DoxyParagraph}{}
Default\+: start\+\_\+light 0~\newline

\end{DoxyParagraph}
\label{_max_005flights}%
\label{_max_005flights-1}%


\subsection*{max\+\_\+lights}

Sets the maximum number of lights which will be considered for use with this pass. \begin{DoxyParagraph}{}
Format\+: max\+\_\+lights $<$number$>$
\end{DoxyParagraph}
The maximum number of lights which can be used when rendering fixed-\/function materials is set by the rendering system, and is typically set at 8. When you are using the programmable pipeline (See \hyperlink{_high-level-_programs_Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass}{Using Vertex/\+Geometry/\+Fragment Programs in a Pass}) this limit is dependent on the program you are running, or, if you use ’iteration once\+\_\+per\+\_\+light’ or a variant (See \hyperlink{_material-_scripts_iteration}{iteration}), it effectively only bounded by the number of passes you are willing to use. If you are not using pass iteration, the light limit applies once for this pass. If you are using pass iteration, the light limit applies across all iterations of this pass -\/ for example if you have 12 lights in range with an ’iteration once\+\_\+per\+\_\+light’ setup but your max\+\_\+lights is set to 4 for that pass, the pass will only iterate 4 times. \begin{DoxyParagraph}{}
Default\+: max\+\_\+lights 8~\newline

\end{DoxyParagraph}
\hypertarget{_material-_scripts_iteration}{}\paragraph{iteration}\label{_material-_scripts_iteration}
Sets whether or not this pass is iterated, i.\+e. issued more than once. \begin{DoxyParagraph}{}
Format 1\+: iteration $<$once $\vert$ once\+\_\+per\+\_\+light$>$ \mbox{[}light\+Type\mbox{]} Format 2\+: iteration $<$number$>$ \mbox{[}$<$per\+\_\+light$>$ \mbox{[}light\+Type\mbox{]}\mbox{]} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Format 3\+: iteration $<$number$>$ \mbox{[}$<$per\+\_\+n\+\_\+lights$>$ $<$num\+\_\+lights$>$ \mbox{[}light\+Type\mbox{]}\mbox{]} Examples\+:
\end{DoxyParagraph}

\begin{DoxyDescription}
\item[iteration once ]

The pass is only executed once which is the default behaviour.


\item[iteration once\+\_\+per\+\_\+light point ]

The pass is executed once for each point light.


\item[iteration 5 ]

The render state for the pass will be setup and then the draw call will execute 5 times.


\item[iteration 5 per\+\_\+light point ]

The render state for the pass will be setup and then the draw call will execute 5 times. This will be done for each point light.


\item[iteration 1 per\+\_\+n\+\_\+lights 2 point ]

The render state for the pass will be setup and the draw call executed once for every 2 lights.


\end{DoxyDescription}~\newline


By default, passes are only issued once. However, if you use the programmable pipeline, or you wish to exceed the normal limits on the number of lights which are supported, you might want to use the once\+\_\+per\+\_\+light option. In this case, only light index 0 is ever used, and the pass is issued multiple times, each time with a different light in light index 0. Clearly this will make the pass more expensive, but it may be the only way to achieve certain effects such as per-\/pixel lighting effects which take into account 1..n lights.

Using a number instead of \char`\"{}once\char`\"{} instructs the pass to iterate more than once after the render state is setup. The render state is not changed after the initial setup so repeated draw calls are very fast and ideal for passes using programmable shaders that must iterate more than once with the same render state i.\+e. shaders that do fur, motion blur, special filtering.

If you use once\+\_\+per\+\_\+light, you should also add an ambient pass to the technique before this pass, otherwise when no lights are in range of this object it will not get rendered at all; this is important even when you have no ambient light in the scene, because you would still want the objects silhouette to appear.

The light\+Type parameter to the attribute only applies if you use once\+\_\+per\+\_\+light, per\+\_\+light, or per\+\_\+n\+\_\+lights and restricts the pass to being run for lights of a single type (either ’point’, ’directional’ or ’spot’). In the example, the pass will be run once per point light. This can be useful because when you’re writing a vertex / fragment program it is a lot easier if you can assume the kind of lights you’ll be dealing with. However at least point and directional lights can be dealt with in one way. Default\+: iteration once

\label{_fur_005fexample}%


Example\+: Simple Fur shader material script that uses a second pass with 10 iterations to grow the fur\+:


\begin{DoxyCode}
\textcolor{comment}{// GLSL simple Fur}
vertex\_program GLSLDemo/FurVS glsl 
\{
  source fur.vert 
  default\_params
  \{
    param\_named\_auto lightPosition light\_position\_object\_space 0
    param\_named\_auto eyePosition camera\_position\_object\_space
    param\_named\_auto passNumber pass\_number
    param\_named\_auto multiPassNumber pass\_iteration\_number
    param\_named furLength \textcolor{keywordtype}{float} 0.15
  \}
\}

fragment\_program GLSLDemo/FurFS glsl 
\{
  source fur.frag 
  default\_params
  \{
    param\_named Ka \textcolor{keywordtype}{float} 0.2
    param\_named Kd \textcolor{keywordtype}{float} 0.5
    param\_named Ks \textcolor{keywordtype}{float} 0.0
    param\_named furTU \textcolor{keywordtype}{int} 0
  \}
\}

material Fur
\{
  technique GLSL
  \{
    pass base\_coat
    \{
      ambient 0.7 0.7 0.7
      diffuse 0.5 0.8 0.5
      specular 1.0 1.0 1.0 1.5

      vertex\_program\_ref GLSLDemo/FurVS
      \{
      \}

      fragment\_program\_ref GLSLDemo/FurFS 
      \{
      \}

      texture\_unit
      \{
        texture Fur.tga
        tex\_coord\_set 0
        filtering trilinear
      \}
    \}

    pass grow\_fur
    \{
      ambient 0.7 0.7 0.7
      diffuse 0.8 1.0 0.8
      specular 1.0 1.0 1.0 64
      depth\_write off

      scene\_blend src\_alpha one
      iteration 10

      vertex\_program\_ref GLSLDemo/FurVS
      \{
      \}

      fragment\_program\_ref GLSLDemo/FurFS
      \{
      \}

      texture\_unit
      \{
        texture Fur.tga
        tex\_coord\_set 0
        filtering trilinear
      \}
    \}
  \}
\}
\end{DoxyCode}


\begin{DoxyNote}{Note}
use gpu program auto parameters \href{#pass_005fnumber}{\tt pass\+\_\+number} and \href{#pass_005fiteration_005fnumber}{\tt pass\+\_\+iteration\+\_\+number} to tell the vertex, geometry or fragment program the pass number and iteration number.
\end{DoxyNote}
\label{_point_005fsize}%
\label{_point_005fsize-1}%


\subsection*{point\+\_\+size}

This setting allows you to change the size of points when rendering a point list, or a list of point sprites. The interpretation of this command depends on the \hyperlink{class_ogre_1_1_pass_a0d44f9c4a2e69fd31a4687ffe2b8335d}{Ogre\+::\+Pass\+::set\+Point\+Attenuation} option -\/ if it is off (the default), the point size is in screen pixels, if it is on, it expressed as normalised screen coordinates (1.\+0 is the height of the screen) when the point is at the origin. \begin{DoxyNote}{Note}
Some drivers have an upper limit on the size of points they support -\/ this can even vary between A\+P\+Is on the same card! Don\textquotesingle{}t rely on point sizes that cause the point sprites to get very large on screen, since they may get clamped on some cards. Upper sizes can range from 64 to 256 pixels.
\end{DoxyNote}
\begin{DoxyParagraph}{}
Format\+: point\+\_\+size $<$size$>$ Default\+: point\+\_\+size 1.\+0
\end{DoxyParagraph}
\label{_point_005fsprites}%
\label{_point_005fsprites-1}%


\subsection*{point\+\_\+sprites}

This setting specifies whether or not hardware point sprite rendering is enabled for this pass. Enabling it means that a point list is rendered as a list of quads rather than a list of dots. It is very useful to use this option if you are using a Billboard\+Set and only need to use point oriented billboards which are all of the same size. You can also use it for any other point list render.

\begin{DoxyParagraph}{}
Format\+: point\+\_\+sprites $<$on$\vert$off$>$ Default\+: point\+\_\+sprites off
\end{DoxyParagraph}
\label{_point_005fsize_005fattenuation}%
\label{_point_005fsize_005fattenuation-1}%


\subsection*{point\+\_\+size\+\_\+attenuation}

Defines whether point size is attenuated with view space distance, and in what fashion.

\begin{DoxyParagraph}{}
Format\+: point\+\_\+size\+\_\+attenuation $<$enabled$>$ \mbox{[}constant linear quadratic\mbox{]} Default\+: point\+\_\+size\+\_\+attenuation off
\end{DoxyParagraph}
When performing point rendering or point sprite rendering, point size can be attenuated with distance. The equation for doing this is

\$\$attenuation = 1 / (constant + linear $\ast$ dist + quadratic $\ast$ d$^\wedge$2)\$\$

For example, to disable distance attenuation (constant screensize) you would set constant to 1, and linear and quadratic to 0. A standard perspective attenuation would be 0, 1, 0 respectively.

The resulting size is clamped to the minimum and maximum point size. 
\begin{DoxyParams}{Parameters}
{\em enabled} & Whether point attenuation is enabled \\
\hline
{\em constant,linear,quadratic} & Parameters to the attenuation function defined above\\
\hline
\end{DoxyParams}
\label{_point_005fsize_005fmin}%
\label{_point_005fsize_005fmin-1}%


\subsection*{point\+\_\+size\+\_\+min}

Sets the minimum point size after attenuation (\href{#point_005fsize_005fattenuation}{\tt point\+\_\+size\+\_\+attenuation}). For details on the size metrics, See \href{#point_005fsize}{\tt point\+\_\+size}. \begin{DoxyParagraph}{}
Format\+: point\+\_\+size\+\_\+min $<$size$>$ Default\+: point\+\_\+size\+\_\+min 0
\end{DoxyParagraph}
\label{_point_005fsize_005fmax}%
\label{_point_005fsize_005fmax-1}%


\subsection*{point\+\_\+size\+\_\+max}

Sets the maximum point size after attenuation (\href{#point_005fsize_005fattenuation}{\tt point\+\_\+size\+\_\+attenuation}). For details on the size metrics, See \href{#point_005fsize}{\tt point\+\_\+size}. A value of 0 means the maximum is set to the same as the max size reported by the current card. \begin{DoxyParagraph}{}
Format\+: point\+\_\+size\+\_\+max $<$size$>$ Default\+: point\+\_\+size\+\_\+max 0
\end{DoxyParagraph}
\label{_line_width}%
 \subsection*{line\+\_\+width}

This property determines what width is used to render lines. \begin{DoxyNote}{Note}
some drivers only support a value of 1.\+0 here
\end{DoxyNote}
\begin{DoxyParagraph}{}
Format\+: line\+\_\+width $<$width$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: line\+\_\+width 1
\end{DoxyParagraph}
\hypertarget{_material-_scripts_Texture-Units}{}\subsubsection{Texture Units}\label{_material-_scripts_Texture-Units}
Here are the attributes you can use in a ’texture\+\_\+unit’ section of a .material script\+:

\label{_Available-Texture-Layer-Attributes}%


\section*{Available Texture Layer Attributes}


\begin{DoxyItemize}
\item \href{#texture_005falias}{\tt texture\+\_\+alias}
\item \href{#texture}{\tt texture}
\item \href{#anim_005ftexture}{\tt anim\+\_\+texture}
\item \href{#cubic_005ftexture}{\tt cubic\+\_\+texture}
\item \href{#tex_005fcoord_005fset}{\tt tex\+\_\+coord\+\_\+set}
\item \href{#tex_005faddress_005fmode}{\tt tex\+\_\+address\+\_\+mode}
\item \href{#tex_005fborder_005fcolour}{\tt tex\+\_\+border\+\_\+colour}
\item \href{#filtering}{\tt filtering}
\item \href{#max_005fanisotropy}{\tt max\+\_\+anisotropy}
\item \href{#mipmap_005fbias}{\tt mipmap\+\_\+bias}
\item \href{#colour_005fop}{\tt colour\+\_\+op}
\item \href{#colour_005fop_005fex}{\tt colour\+\_\+op\+\_\+ex}
\item \href{#colour_005fop_005fmultipass_005ffallback}{\tt colour\+\_\+op\+\_\+multipass\+\_\+fallback}
\item \href{#alpha_005fop_005fex}{\tt alpha\+\_\+op\+\_\+ex}
\item \href{#env_005fmap}{\tt env\+\_\+map}
\item \href{#scroll}{\tt scroll}
\item \href{#scroll_005fanim}{\tt scroll\+\_\+anim}
\item \href{#rotate}{\tt rotate}
\item \href{#rotate_005fanim}{\tt rotate\+\_\+anim}
\item \href{#scale}{\tt scale}
\item \href{#wave_005fxform}{\tt wave\+\_\+xform}
\item \href{#transform}{\tt transform}
\item \href{#binding_005ftype}{\tt binding\+\_\+type}
\item \href{#content_005ftype}{\tt content\+\_\+type}
\end{DoxyItemize}

You can also use a nested ’texture\+\_\+source’ section in order to use a special add-\/in as a source of texture data, See \hyperlink{External-Texture-Sources}{External Texture Sources} for details.

\label{_Attribute-Descriptions-1}%


\section*{Attribute Descriptions}

\label{_texture_005falias}%
\label{_texture_005falias-1}%


\subsection*{texture\+\_\+alias}

Sets the alias name for this texture unit. \begin{DoxyParagraph}{}
Format\+: texture\+\_\+alias $<$name$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: texture\+\_\+alias Normal\+Map
\end{DoxyParagraph}
Setting the texture alias name is useful if this material is to be inherited by other other materials and only the textures will be changed in the new material.(See \hyperlink{_material-_scripts_Texture-Aliases}{Texture Aliases}) Default\+: If a texture\+\_\+unit has a name then the texture\+\_\+alias defaults to the texture\+\_\+unit name.

\label{_texture}%
\label{_texture-1}%


\subsection*{texture}

Sets the name of the static texture image this layer will use. \begin{DoxyParagraph}{}
Format\+: texture $<$texturename$>$ \mbox{[}$<$type$>$\mbox{]} \mbox{[}unlimited $\vert$ num\+Mip\+Maps\mbox{]} \mbox{[}alpha\mbox{]} \mbox{[}$<$Pixel\+Format$>$\mbox{]} \mbox{[}gamma\mbox{]} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: texture funkywall.\+jpg
\end{DoxyParagraph}
This setting is mutually exclusive with the anim\+\_\+texture attribute. Note that the texture file cannot include spaces. Those of you Windows users who like spaces in filenames, please get over it and use underscores instead.


\begin{DoxyParams}{Parameters}
{\em type} & specify a the type of texture to create -\/ the default is ’2d’, but you can override this; here’s the full list\+: 
\begin{DoxyDescription}
\item[1d ]

A 1-\/dimensional texture; that is, a texture which is only 1 pixel high. These kinds of textures can be useful when you need to encode a function in a texture and use it as a simple lookup, perhaps in a fragment program. It is important that you use this setting when you use a fragment program which uses 1-\/dimensional texture coordinates, since GL requires you to use a texture type that matches (D3D will let you get away with it, but you ought to plan for cross-\/compatibility). Your texture widths should still be a power of 2 for best compatibility and performance.


\item[2d ]

The default type which is assumed if you omit it, your texture has a width and a height, both of which should preferably be powers of 2, and if you can, make them square because this will look best on the most hardware. These can be addressed with 2D texture coordinates.


\item[3d ]

A 3 dimensional texture i.\+e. volume texture. Your texture has a width, a height, both of which should be powers of 2, and has depth. These can be addressed with 3d texture coordinates i.\+e. through a pixel shader.


\item[cubic ]

This texture is made up of 6 2D textures which are pasted around the inside of a cube. The base\+\_\+name in this format is something like ’skybox.\+jpg’, and the system will expect you to provide skybox\+\_\+fr.\+jpg, skybox\+\_\+bk.\+jpg, skybox\+\_\+up.\+jpg, skybox\+\_\+dn.\+jpg, skybox\+\_\+lf.\+jpg, and skybox\+\_\+rt.\+jpg for the individual faces. Alternatively 1 cube texture can be used if supported by the texture format(\+D\+D\+S for example) and rendersystem. Can be addressed with 3D texture coordinates and are useful for cubic reflection maps and normal maps.  
\end{DoxyDescription}\\
\hline
{\em num\+Mip\+Maps} & specify the number of mipmaps to generate for this texture. The default is ’unlimited’ which means mips down to 1x1 size are generated. You can specify a fixed number (even 0) if you like instead. Note that if you use the same texture in many material scripts, the number of mipmaps generated will conform to the number specified in the first texture\+\_\+unit used to load the texture -\/ so be consistent with your usage.\\
\hline
{\em alpha} & specify that a single channel (luminance) texture should be loaded as alpha rather than the default which is to load it into the red channel. This can be helpful if you want to use alpha-\/only textures in the fixed function pipeline. Default\+: none\\
\hline
{\em Pixel\+Format} & specify the desired pixel format of the texture to create, which may be different to the pixel format of the texture file being loaded. Bear in mind that the final pixel format will be constrained by hardware capabilities so you may not get exactly what you ask for. Names defined in \hyperlink{group___image_ga7e0353e7d36d4c2e8468641b7303d39c}{Ogre\+::\+Pixel\+Format} are valid values.\\
\hline
{\em gamma} & informs the renderer that you want the graphics hardware to perform gamma correction on the texture values as they are sampled for rendering. This is only applicable for textures which have 8-\/bit colour channels (e.\+g.\+P\+F\+\_\+\+R8\+G8\+B8). Often, 8-\/bit per channel textures will be stored in gamma space in order to increase the precision of the darker colours (\href{http://en.wikipedia.org/wiki/Gamma_correction}{\tt http\+://en.\+wikipedia.\+org/wiki/\+Gamma\+\_\+correction}) but this can throw out blending and filtering calculations since they assume linear space colour values. For the best quality shading, you may want to enable gamma correction so that the hardware converts the texture values to linear space for you automatically when sampling the texture, then the calculations in the pipeline can be done in a reliable linear colour space. When rendering to a final 8-\/bit per channel display, you’ll also want to convert back to gamma space which can be done in your shader (by raising to the power 1/2.\+2) or you can enable gamma correction on the texture being rendered to or the render window. Note that the ’gamma’ option on textures is applied on loading the texture so must be specified consistently if you use this texture in multiple places.\\
\hline
\end{DoxyParams}
\label{_anim_005ftexture}%
\label{_anim_005ftexture-1}%


\subsection*{anim\+\_\+texture}

Sets the images to be used in an animated texture layer. There are 2 formats, one for implicitly determined image names, one for explicitly named images. \begin{DoxyParagraph}{}
Format1 (short)\+: anim\+\_\+texture $<$name$>$ $<$num\+Frames$>$ $<$duration$>$
\end{DoxyParagraph}
Animated textures are just a series of images making up the frames of the animation. All the images must be the same size, and their names must have a frame number appended before the extension, e.\+g. if you specify a name of \char`\"{}flame.\+jpg\char`\"{} with 3 frames, the image names must be \char`\"{}flame\+\_\+0.\+jpg\char`\"{}, \char`\"{}flame\+\_\+1.\+jpg\char`\"{} and \char`\"{}flame\+\_\+2.\+jpg\char`\"{}.

You can change the active frame on a texture layer by calling the set\+Current\+Frame method. \begin{DoxyNote}{Note}
If you can\textquotesingle{}t make your texture images conform to the naming standard laid out here, you can call the alternative set\+Animated\+Texture\+Name method which takes an array of names instead. 
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em name} & The base name of the textures to use e.\+g. flame.\+jpg for frames flame\+\_\+0.\+jpg, flame\+\_\+1.\+jpg etc. \\
\hline
{\em num\+Frames} & The number of frames in the sequence. \\
\hline
{\em duration} & The length of time it takes to display the whole animation sequence, in seconds. If 0, no automatic transition occurs.\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Example\+: anim\+\_\+texture flame.\+jpg 5 2.\+5
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Format2 (long)\+: anim\+\_\+texture $<$frame1$>$ $<$frame2$>$ ... $<$duration$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: anim\+\_\+texture flamestart.\+jpg flamemore.\+png flameagain.\+jpg moreflame.\+jpg lastflame.\+tga 2.\+5
\end{DoxyParagraph}
This sets up the same duration animation but from 5 separately named image files. The first format is more concise, but the second is provided if you cannot make your images conform to the naming standard required for it. \begin{DoxyParagraph}{}
Default\+: none
\end{DoxyParagraph}
\label{_cubic_005ftexture}%
\label{_cubic_005ftexture-1}%


\subsection*{cubic\+\_\+texture}

Sets the images used in a cubic texture, i.\+e. one made up of 6 individual images making up the faces of a cube or 1 cube texture if supported by the texture format(\+D\+D\+S for example) and rendersystem.. These kinds of textures are used for reflection maps (if hardware supports cubic reflection maps) or skyboxes. There are 2 formats, a brief format expecting image names of a particular format and a more flexible but longer format for arbitrarily named textures. \begin{DoxyParagraph}{}
Format1 (short)\+: cubic\+\_\+texture $<$base\+\_\+name$>$ $<$combined\+U\+V\+W$\vert$separate\+UV$>$
\end{DoxyParagraph}
The base\+\_\+name in this format is something like ’skybox.\+jpg’, and the system will expect you to provide skybox\+\_\+fr.\+jpg, skybox\+\_\+bk.\+jpg, skybox\+\_\+up.\+jpg, skybox\+\_\+dn.\+jpg, skybox\+\_\+lf.\+jpg, and skybox\+\_\+rt.\+jpg for the individual faces. \begin{DoxyParagraph}{}
Format2 (long)\+: cubic\+\_\+texture $<$front$>$ $<$back$>$ $<$left$>$ $<$right$>$ $<$up$>$ $<$down$>$ separate\+UV
\end{DoxyParagraph}
In this case each face is specified explicitly, incase you don’t want to conform to the image naming standards above. You can only use this for the separate\+UV version since the combined\+U\+VW version requires a single texture name to be assigned to the combined 3D texture (see below).

In both cases the final parameter means the following\+:


\begin{DoxyDescription}
\item[separate\+UV ]

The 6 textures are kept separate but are all referenced by this single texture layer. One texture at a time is active (they are actually stored as 6 frames), and they are addressed using standard 2D UV coordinates.

\begin{DoxyNote}{Note}
This type is only useful with skyboxes where only one face is rendered at a time. For everything else real cubic textures are better due to hardware support.  
\end{DoxyNote}

\item[combined\+U\+VW ]

The 6 textures are combined into a single ’cubic’ texture map which is then addressed using 3D texture coordinates.

\begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000166}{Deprecated}]use the format {\ttfamily texture $<$basename$>$ cubic} instead\end{DoxyRefDesc}



\end{DoxyDescription}~\newline
 \begin{DoxyParagraph}{}
Default\+: none
\end{DoxyParagraph}
\label{_binding_005ftype}%
\label{_binding_005ftype-1}%


\subsection*{binding\+\_\+type}

Some render systems, when implementing vertex texture fetch, separate the binding of textures for use in the vertex program versus those used in fragment programs. This setting allows you to target the vertex processing unit with a texture binding, in those cases. For rendersystems which have a unified binding for the vertex and fragment units, this setting makes no difference. \begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000158}{Deprecated}]see \hyperlink{class_ogre_1_1_texture_unit_state_a411bcf3e69280ce146f09ddc73d9e7e8}{Ogre\+::\+Texture\+Unit\+State\+::\+Binding\+Type} comment \end{DoxyRefDesc}


\begin{DoxySeeAlso}{See also}
\hyperlink{_high-level-_programs_Vertex-Texture-Fetch}{Vertex Texture Fetch}
\end{DoxySeeAlso}
Format\+: binding\+\_\+type $<$vertex$\vert$fragment$>$ \begin{DoxyParagraph}{}
Default\+: binding\+\_\+type fragment
\end{DoxyParagraph}
\label{_content_005ftype}%
\label{_content_005ftype-1}%


\subsection*{content\+\_\+type}

Tells this texture unit where it should get its content from. The default is to get texture content from a named texture, as defined with the \href{#texture}{\tt texture}, \href{#cubic_005ftexture}{\tt cubic\+\_\+texture}, \href{#anim_005ftexture}{\tt anim\+\_\+texture} attributes. However you can also pull texture information from other automated sources.

\begin{DoxyParagraph}{}
Format\+: content\+\_\+type $<$type$>$ \mbox{[}$<$compositor\+Name$>$\mbox{]} \mbox{[}$<$texture\+Name$>$\mbox{]} \mbox{[}$<$mrt\+Index$>$\mbox{]}
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em type} & 
\begin{DoxyDescription}
\item[named ]

The default option, this derives texture content from a texture name, loaded by ordinary means from a file or having been manually created with a given name.


\item[shadow ]

This option allows you to pull in a shadow texture, and is only valid when you use texture shadows and one of the ’custom sequence’ shadowing types (See \hyperlink{Shadows}{Shadows}). The shadow texture in question will be from the ’n’th closest light that casts shadows, unless you use light-\/based pass iteration or the light\+\_\+start option which may start the light index higher. When you use this option in multiple texture units within the same pass, each one references the next shadow texture. The shadow texture index is reset in the next pass, in case you want to take into account the same shadow textures again in another pass (e.\+g. a separate specular / gloss pass). By using this option, the correct light frustum projection is set up for you for use in fixed-\/function, if you use shaders just reference the texture\+\_\+viewproj\+\_\+matrix auto parameter in your shader.


\item[compositor ]

This option allows you to reference a texture from a compositor, and is only valid when the pass is rendered within a compositor sequence. This can be either in a render\+\_\+scene directive inside a compositor script, or in a general pass in a viewport that has a compositor attached. Note that this is a reference only, meaning that it does not change the render order. You must make sure that the order is reasonable for what you are trying to achieve (for example, texture pooling might cause the referenced texture to be overwritten by something else by the time it is referenced). This can be either in a render\+\_\+scene directive inside a compositor script, or in a general pass in a viewport that has a compositor attached. Note that this is a reference only, meaning that it does not change the render order. You must make sure that the order is reasonable for what you are trying to achieve (for example, texture pooling might cause the referenced texture to be overwritten by something else by the time it is referenced).


\end{DoxyDescription}\\
\hline
\end{DoxyParams}
Only valid when content type is compositor. 
\begin{DoxyParams}{Parameters}
{\em compositor\+Name} & The name of the compositor to reference. \\
\hline
{\em texture\+Name} & The name of the texture to reference. \\
\hline
{\em mrt\+Index} & The index of the wanted texture, if referencing an M\+RT.\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Example\+: content\+\_\+type compositor Depth\+Compositor Output\+Texture
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: content\+\_\+type named
\end{DoxyParagraph}
\label{_tex_005fcoord_005fset}%
\label{_tex_005fcoord_005fset-1}%


\subsection*{tex\+\_\+coord\+\_\+set}

Sets which texture coordinate set is to be used for this texture layer. A mesh can define multiple sets of texture coordinates, this sets which one this material uses.

\begin{DoxyParagraph}{}
Format\+: tex\+\_\+coord\+\_\+set $<$set\+\_\+num$>$
\end{DoxyParagraph}
\begin{DoxyNote}{Note}
Only has an effect with the fixed-\/function pipeline or the \hyperlink{rtss}{R\+T\+S\+S\+: Run Time Shader System}
\end{DoxyNote}
\begin{DoxyParagraph}{}
Example\+: tex\+\_\+coord\+\_\+set 2 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: tex\+\_\+coord\+\_\+set 0
\end{DoxyParagraph}
\label{_tex_005faddress_005fmode}%
\label{_tex_005faddress_005fmode-1}%


\subsection*{tex\+\_\+address\+\_\+mode}

Defines what happens when texture coordinates exceed 1.\+0 for this texture layer.\+You can use the simple format to specify the addressing mode for all 3 potential texture coordinates at once, or you can use the 2/3 parameter extended format to specify a different mode per texture coordinate. \begin{DoxyParagraph}{}
Simple Format\+: tex\+\_\+address\+\_\+mode $<$uvw\+\_\+mode$>$ ~\newline
 Extended Format\+: tex\+\_\+address\+\_\+mode $<$u\+\_\+mode$>$ $<$v\+\_\+mode$>$ \mbox{[}$<$w\+\_\+mode$>$\mbox{]}
\end{DoxyParagraph}
Valid values for both are one of \hyperlink{class_ogre_1_1_texture_unit_state_a47c5a9f4fc08159b99bdc51103bcf852}{Ogre\+::\+Texture\+Unit\+State\+::\+Texture\+Addressing\+Mode} without the {\ttfamily T\+A\+M\+\_\+} prefix. E.\+g. {\ttfamily T\+A\+M\+\_\+\+W\+R\+AP} becomes {\ttfamily wrap}.

\begin{DoxyParagraph}{}
Default\+: tex\+\_\+address\+\_\+mode wrap
\end{DoxyParagraph}
\label{_tex_005fborder_005fcolour}%
\label{_tex_005fborder_005fcolour-1}%


\subsection*{tex\+\_\+border\+\_\+colour}

Sets the border colour of border texture address mode (see \href{#tex_005faddress_005fmode}{\tt tex\+\_\+address\+\_\+mode}). \begin{DoxyParagraph}{}
Format\+: tex\+\_\+border\+\_\+colour $<$red$>$ $<$green$>$ $<$blue$>$ \mbox{[}$<$alpha$>$\mbox{]}~\newline
 NB valid colour values are between 0.\+0 and 1.\+0. 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: tex\+\_\+border\+\_\+colour 0.\+0 1.\+0 0.\+3 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: tex\+\_\+border\+\_\+colour 0.\+0 0.\+0 0.\+0 1.\+0
\end{DoxyParagraph}
\label{_filtering}%
\label{_filtering-1}%


\subsection*{filtering}

Sets the type of texture filtering used when magnifying or minifying a texture. There are 2 formats to this attribute, the simple format where you simply specify the name of a predefined set of filtering options, and the complex format, where you individually set the minification, magnification, and mip filters yourself.

\subsubsection*{Simple Format}

With this format, you only need to provide a single parameter

\begin{DoxyParagraph}{}
Format\+: filtering $<$none$\vert$bilinear$\vert$trilinear$\vert$anisotropic$>$~\newline
 Default\+: filtering bilinear
\end{DoxyParagraph}

\begin{DoxyDescription}
\item[none ]No filtering or mipmapping is used. Equal to\+: min=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3dad299986d6ba4f220cc628a1b9a4f6a52}{Ogre\+::\+F\+O\+\_\+\+P\+O\+I\+NT}, mag=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3dad299986d6ba4f220cc628a1b9a4f6a52}{Ogre\+::\+F\+O\+\_\+\+P\+O\+I\+NT}, mip=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da0be36e268ed5d2d25fe91ba5b5f769b5}{Ogre\+::\+F\+O\+\_\+\+N\+O\+NE}  
\item[bilinear ]2x2 box filtering is performed when magnifying or reducing a texture, and a mipmap is picked from the list but no filtering is done between the levels of the mipmaps. Equal to\+: min=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da6b0e1f92a9531879e2f0acfe5e5183c6}{Ogre\+::\+F\+O\+\_\+\+L\+I\+N\+E\+AR}, mag=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da6b0e1f92a9531879e2f0acfe5e5183c6}{Ogre\+::\+F\+O\+\_\+\+L\+I\+N\+E\+AR}, mip=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3dad299986d6ba4f220cc628a1b9a4f6a52}{Ogre\+::\+F\+O\+\_\+\+P\+O\+I\+NT}  
\item[trilinear ]2x2 box filtering is performed when magnifying and reducing a texture, and the closest 2 mipmaps are filtered together. Equal to\+: min=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da6b0e1f92a9531879e2f0acfe5e5183c6}{Ogre\+::\+F\+O\+\_\+\+L\+I\+N\+E\+AR}, mag=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da6b0e1f92a9531879e2f0acfe5e5183c6}{Ogre\+::\+F\+O\+\_\+\+L\+I\+N\+E\+AR}, mip=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da6b0e1f92a9531879e2f0acfe5e5183c6}{Ogre\+::\+F\+O\+\_\+\+L\+I\+N\+E\+AR}  
\item[anisotropic ]This is the same as ’trilinear’, except the filtering algorithm takes account of the slope of the triangle in relation to the camera rather than simply doing a 2x2 pixel filter in all cases. Equal to\+: min=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da0ced0c8e18f83505a73c7275563d4372}{Ogre\+::\+F\+O\+\_\+\+A\+N\+I\+S\+O\+T\+R\+O\+P\+IC}, max=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da0ced0c8e18f83505a73c7275563d4372}{Ogre\+::\+F\+O\+\_\+\+A\+N\+I\+S\+O\+T\+R\+O\+P\+IC}, mip=\hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da6b0e1f92a9531879e2f0acfe5e5183c6}{Ogre\+::\+F\+O\+\_\+\+L\+I\+N\+E\+AR}  
\end{DoxyDescription}

\subsubsection*{Complex Format}

This format gives you complete control over the minification, magnification, and mip filters.

\begin{DoxyParagraph}{}
Format\+: filtering $<$min\+Filter$>$ $<$mag\+Filter$>$ $<$mip\+Filter$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: filtering linear linear point
\end{DoxyParagraph}
Each parameter can be one of \hyperlink{group___general_ga02306c6246268d35f45ad22278bd5d3d}{Ogre\+::\+Filter\+Options} without the {\ttfamily F\+O\+\_\+} prefix. E.\+g. {\ttfamily F\+O\+\_\+\+L\+I\+N\+E\+AR} becomes {\ttfamily linear}.


\begin{DoxyParams}{Parameters}
{\em min\+Filter} & The filtering to use when reducing the size of the texture. Can be \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3dad299986d6ba4f220cc628a1b9a4f6a52}{Ogre\+::\+F\+O\+\_\+\+P\+O\+I\+NT}, \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da6b0e1f92a9531879e2f0acfe5e5183c6}{Ogre\+::\+F\+O\+\_\+\+L\+I\+N\+E\+AR} or \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da0ced0c8e18f83505a73c7275563d4372}{Ogre\+::\+F\+O\+\_\+\+A\+N\+I\+S\+O\+T\+R\+O\+P\+IC}. \\
\hline
{\em mag\+Filter} & The filtering to use when increasing the size of the texture. Can be \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3dad299986d6ba4f220cc628a1b9a4f6a52}{Ogre\+::\+F\+O\+\_\+\+P\+O\+I\+NT}, \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da6b0e1f92a9531879e2f0acfe5e5183c6}{Ogre\+::\+F\+O\+\_\+\+L\+I\+N\+E\+AR} or \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da0ced0c8e18f83505a73c7275563d4372}{Ogre\+::\+F\+O\+\_\+\+A\+N\+I\+S\+O\+T\+R\+O\+P\+IC}. \\
\hline
{\em mip\+Filter} & The filtering to use between mip levels. Can be \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da0be36e268ed5d2d25fe91ba5b5f769b5}{Ogre\+::\+F\+O\+\_\+\+N\+O\+NE} (turns off mipmapping), \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3dad299986d6ba4f220cc628a1b9a4f6a52}{Ogre\+::\+F\+O\+\_\+\+P\+O\+I\+NT} or \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da6b0e1f92a9531879e2f0acfe5e5183c6}{Ogre\+::\+F\+O\+\_\+\+L\+I\+N\+E\+AR} (trilinear filtering).\\
\hline
\end{DoxyParams}
\label{_max_005fanisotropy}%
\label{_max_005fanisotropy-1}%


\subsection*{max\+\_\+anisotropy}

Sets the anisotropy level to be used for this texture level.

\begin{DoxyParagraph}{}
Format\+: max\+\_\+anisotropy $<$max\+Aniso$>$~\newline
 Default\+: max\+\_\+anisotropy 1
\end{DoxyParagraph}
The degree of anisotropy is the ratio between the height of the texture segment visible in a screen space region versus the width -\/ so for example a floor plane, which stretches on into the distance and thus the vertical texture coordinates change much faster than the horizontal ones, has a higher anisotropy than a wall which is facing you head on (which has an anisotropy of 1 if your line of sight is perfectly perpendicular to it).The maximum value is determined by the hardware, but it is usually 8 or 16.

In order for this to be used, you have to set the minification and/or the magnification option on this texture to \hyperlink{group___general_gga02306c6246268d35f45ad22278bd5d3da0ced0c8e18f83505a73c7275563d4372}{Ogre\+::\+F\+O\+\_\+\+A\+N\+I\+S\+O\+T\+R\+O\+P\+IC}. 
\begin{DoxyParams}{Parameters}
{\em max\+Aniso} & The maximal anisotropy level, should be between 2 and the maximum supported by hardware (1 is the default, ie. no anisotrophy).\\
\hline
\end{DoxyParams}
\label{_mipmap_005fbias}%
\label{_mipmap_005fbias-1}%


\subsection*{mipmap\+\_\+bias}

You can alter the mipmap calculation by biasing the result with a single floating point value. After the mip level has been calculated, this bias value is added to the result to give the final mip level. Lower mip levels are larger (higher detail), so a negative bias will force the larger mip levels to be used, and a positive bias will cause smaller mip levels to be used. The bias values are in mip levels, so a -\/1 bias will force mip levels one larger than by the default calculation.

In order for this option to be used, your hardware has to support mipmap biasing (exposed through \hyperlink{group___render_system_gga3d2965b7f378ebdcfe8a4a6cf74c3de7a059362950c064bfe870e5fe60b56a3ca}{Ogre\+::\+R\+S\+C\+\_\+\+M\+I\+P\+M\+A\+P\+\_\+\+L\+O\+D\+\_\+\+B\+I\+AS}), and your minification filtering has to be set to point or linear.

\begin{DoxyParagraph}{}
Format\+: mipmap\+\_\+bias $<$value$>$~\newline
 Default\+: mipmap\+\_\+bias 0
\end{DoxyParagraph}
\label{_colour_005fop}%
\label{_colour_005fop-1}%


\subsection*{colour\+\_\+op}

\begin{DoxyNote}{Note}
Only has an effect with the fixed-\/function pipeline or the \hyperlink{rtss}{R\+T\+S\+S\+: Run Time Shader System}
\end{DoxyNote}
Determines how the colour of this texture layer is combined with the one below it (or the lighting effect on the geometry if this is the first layer). \begin{DoxyParagraph}{}
Format\+: colour\+\_\+op $<$op$>$
\end{DoxyParagraph}
This method is the simplest way to blend texture layers, because it requires only one parameter, gives you the most common blending types, and automatically sets up 2 blending methods\+: one for if single-\/pass multitexturing hardware is available, and another for if it is not and the blending must be achieved through multiple rendering passes. It is, however, quite limited and does not expose the more flexible multitexturing operations, simply because these can\textquotesingle{}t be automatically supported in multipass fallback mode. If want to use the fancier options, use \hyperlink{class_ogre_1_1_texture_unit_state_a5f3994ce2f61c6c6fee6fe8f89c9e369}{Ogre\+::\+Texture\+Unit\+State\+::set\+Colour\+Operation\+Ex}, but you\textquotesingle{}ll either have to be sure that enough multitexturing units will be available, or you should explicitly set a fallback using \hyperlink{class_ogre_1_1_texture_unit_state_a1c4dcca2a0d343dc6660b9071cd4c79f}{Ogre\+::\+Texture\+Unit\+State\+::set\+Colour\+Op\+Multipass\+Fallback}. \begin{DoxyNote}{Note}
The default method is \hyperlink{group___materials_ggabcbb38d1ac195e4be401f85b7ab0da8fa20815cab41c35f08f3520fb404b95efd}{Ogre\+::\+L\+B\+O\+\_\+\+M\+O\+D\+U\+L\+A\+TE} for all layers. 
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em op} & One of the \hyperlink{group___materials_gabcbb38d1ac195e4be401f85b7ab0da8f}{Ogre\+::\+Layer\+Blend\+Operation} enumerated blending types. Without the {\ttfamily L\+B\+O\+\_\+} prefix. E.\+g. {\ttfamily L\+B\+O\+\_\+\+R\+E\+P\+L\+A\+CE} becomes {\ttfamily replace}.\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Default\+: colour\+\_\+op modulate
\end{DoxyParagraph}
\label{_colour_005fop_005fex}%
\label{_colour_005fop_005fex-1}%


\subsection*{colour\+\_\+op\+\_\+ex}

\begin{DoxyNote}{Note}
Only has an effect with the fixed-\/function pipeline or the \hyperlink{rtss}{R\+T\+S\+S\+: Run Time Shader System} 
\end{DoxyNote}
\begin{DoxyParagraph}{}
Format\+: colour\+\_\+op\+\_\+ex $<$op$>$ $<$source1$>$ $<$source2$>$ \mbox{[}$<$manual\+Blend$>$\mbox{]} \mbox{[}$<$arg1$>$\mbox{]} \mbox{[}$<$arg2$>$\mbox{]} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example colour\+\_\+op\+\_\+ex add\+\_\+signed src\+\_\+manual src\+\_\+current 0.\+5
\end{DoxyParagraph}
This is an extended version of the \hyperlink{class_ogre_1_1_texture_unit_state_aa47f44936c3090c97d8b4179333a208b}{Ogre\+::\+Texture\+Unit\+State\+::set\+Colour\+Operation} method which allows extremely detailed control over the blending applied between this and earlier layers. See the Warning below about the issues between mulitpass and multitexturing that using this method can create.

Texture colour operations determine how the final colour of the surface appears when rendered. Texture units are used to combine colour values from various sources (ie. the diffuse colour of the surface from lighting calculations, combined with the colour of the texture). This method allows you to specify the \textquotesingle{}operation\textquotesingle{} to be used, ie. the calculation such as adds or multiplies, and which values to use as arguments, such as a fixed value or a value from a previous calculation.

The defaults for each layer are\+:
\begin{DoxyItemize}
\item op = \hyperlink{group___materials_gga264ecab38a04d01e2c3158fa05ec1ee2a985f2ec53a477d7c19b41700589cb519}{Ogre\+::\+L\+B\+X\+\_\+\+M\+O\+D\+U\+L\+A\+TE}
\item source1 = \hyperlink{group___materials_ggae2ad78de344f35307ce35157c175625ea45f1a14042993f460992b3253ce6ae80}{Ogre\+::\+L\+B\+S\+\_\+\+T\+E\+X\+T\+U\+RE}
\item source2 = \hyperlink{group___materials_ggae2ad78de344f35307ce35157c175625ea370f25da69381c74ca1fc51fde81e659}{Ogre\+::\+L\+B\+S\+\_\+\+C\+U\+R\+R\+E\+NT}
\end{DoxyItemize}

ie. each layer takes the colour results of the previous layer, and multiplies them with the new texture being applied. Bear in mind that colours are R\+GB values from 0.\+0 -\/ 1.\+0 so multiplying them together will result in values in the same range, \textquotesingle{}tinted\textquotesingle{} by the multiply. Note however that a straight multiply normally has the effect of darkening the textures -\/ for this reason there are brightening operations like \hyperlink{group___materials_gga264ecab38a04d01e2c3158fa05ec1ee2a83964282d9ea36a25f4718ae962f8d1c}{Ogre\+::\+L\+B\+X\+\_\+\+M\+O\+D\+U\+L\+A\+T\+E\+\_\+\+X2}. See the \hyperlink{group___materials_gabcbb38d1ac195e4be401f85b7ab0da8f}{Ogre\+::\+Layer\+Blend\+Operation} and \hyperlink{group___materials_gae2ad78de344f35307ce35157c175625e}{Ogre\+::\+Layer\+Blend\+Source} enumerated types for full details. \begin{DoxyNote}{Note}
Because of the limitations on some underlying A\+P\+Is (Direct3D included) the \hyperlink{group___materials_ggae2ad78de344f35307ce35157c175625ea45f1a14042993f460992b3253ce6ae80}{Ogre\+::\+L\+B\+S\+\_\+\+T\+E\+X\+T\+U\+RE} argument can only be used as the first argument, not the second.
\end{DoxyNote}
The final 3 parameters are only required if you decide to pass values manually into the operation, i.\+e. you want one or more of the inputs to the colour calculation to come from a fixed value that you supply. Hence you only need to fill these in if you supply \hyperlink{group___materials_ggae2ad78de344f35307ce35157c175625ea9aad692ea2c7081237095c3ab4044f17}{Ogre\+::\+L\+B\+S\+\_\+\+M\+A\+N\+U\+AL} to the corresponding source, or use the \hyperlink{group___materials_gga264ecab38a04d01e2c3158fa05ec1ee2adbe5957a946513e0f8be8c571f9b73fe}{Ogre\+::\+L\+B\+X\+\_\+\+B\+L\+E\+N\+D\+\_\+\+M\+A\+N\+U\+AL} operation. \begin{DoxyWarning}{Warning}
\hyperlink{namespace_ogre}{Ogre} tries to use multitexturing hardware to blend texture layers together. However, if it runs out of texturing units (e.\+g. 2 of a Ge\+Force2, 4 on a Ge\+Force3) it has to fall back on multipass rendering, i.\+e. rendering the same object multiple times with different textures. This is both less efficient and there is a smaller range of blending operations which can be performed. For this reason, if you use this method you M\+U\+ST also call \hyperlink{class_ogre_1_1_texture_unit_state_a1c4dcca2a0d343dc6660b9071cd4c79f}{Ogre\+::\+Texture\+Unit\+State\+::set\+Colour\+Op\+Multipass\+Fallback} to specify which effect you want to fall back on if sufficient hardware is not available. 

If you wish to avoid having to do this, use the simpler \hyperlink{class_ogre_1_1_texture_unit_state_aa47f44936c3090c97d8b4179333a208b}{Ogre\+::\+Texture\+Unit\+State\+::set\+Colour\+Operation} method which allows less flexible blending options but sets up the multipass fallback automatically, since it only allows operations which have direct multipass equivalents. 
\end{DoxyWarning}

\begin{DoxyParams}{Parameters}
{\em op} & The operation to be used, e.\+g. modulate (multiply), add, subtract. \\
\hline
{\em source1} & The source of the first colour to the operation e.\+g. texture colour. \\
\hline
{\em source2} & The source of the second colour to the operation e.\+g. current surface colour. \\
\hline
{\em arg1} & Manually supplied colour value (only required if source1 = L\+B\+S\+\_\+\+M\+A\+N\+U\+AL). \\
\hline
{\em arg2} & Manually supplied colour value (only required if source2 = L\+B\+S\+\_\+\+M\+A\+N\+U\+AL). \\
\hline
{\em manual\+Blend} & Manually supplied \textquotesingle{}blend\textquotesingle{} value -\/ only required for operations which require manual blend e.\+g. L\+B\+X\+\_\+\+B\+L\+E\+N\+D\+\_\+\+M\+A\+N\+U\+AL.\\
\hline
\end{DoxyParams}
Each parameter can be one of \hyperlink{group___materials_ga264ecab38a04d01e2c3158fa05ec1ee2}{Ogre\+::\+Layer\+Blend\+Operation\+Ex} or \hyperlink{group___materials_gae2ad78de344f35307ce35157c175625e}{Ogre\+::\+Layer\+Blend\+Source} without the prefix. E.\+g. {\ttfamily L\+B\+X\+\_\+\+M\+O\+D\+U\+L\+A\+T\+E\+\_\+\+X4} becomes {\ttfamily modulate\+\_\+x4}.

\begin{DoxyParagraph}{}
Default\+: none (colour\+\_\+op modulate)~\newline

\end{DoxyParagraph}
\label{_colour_005fop_005fmultipass_005ffallback}%
\label{_colour_005fop_005fmultipass_005ffallback-1}%


\subsection*{colour\+\_\+op\+\_\+multipass\+\_\+fallback}

Sets the multipass fallback operation for this layer, if you used colour\+\_\+op\+\_\+ex and not enough multitexturing hardware is available. \begin{DoxyParagraph}{}
Format\+: colour\+\_\+op\+\_\+multipass\+\_\+fallback $<$src\+\_\+factor$>$ $<$dest\+\_\+factor$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: colour\+\_\+op\+\_\+multipass\+\_\+fallback one one\+\_\+minus\+\_\+dest\+\_\+alpha
\end{DoxyParagraph}
Because some effects exposed using \hyperlink{class_ogre_1_1_texture_unit_state_a5f3994ce2f61c6c6fee6fe8f89c9e369}{Ogre\+::\+Texture\+Unit\+State\+::set\+Colour\+Operation\+Ex} are only supported under multitexturing hardware, if the hardware is lacking the system must fallback on multipass rendering, which unfortunately doesn\textquotesingle{}t support as many effects. This method is for you to specify the fallback operation which most suits you.

You\textquotesingle{}ll notice that the interface is the same as the Ogre\+::\+T\+Material\+::set\+Scene\+Blending method; this is because multipass rendering IS effectively scene blending, since each layer is rendered on top of the last using the same mechanism as making an object transparent, it\textquotesingle{}s just being rendered in the same place repeatedly to get the multitexture effect.

If you use the simpler (and hence less flexible) \hyperlink{class_ogre_1_1_texture_unit_state_aa47f44936c3090c97d8b4179333a208b}{Ogre\+::\+Texture\+Unit\+State\+::set\+Colour\+Operation} method you don\textquotesingle{}t need to call this as the system sets up the fallback for you. \begin{DoxyNote}{Note}
This option has no effect in the programmable pipeline, because there is no multipass fallback and multitexture blending is handled by the fragment shader.
\end{DoxyNote}
\label{_alpha_005fop_005fex}%
\label{_alpha_005fop_005fex-1}%


\subsection*{alpha\+\_\+op\+\_\+ex}

\begin{DoxyNote}{Note}
Only has an effect with the fixed-\/function pipeline or the \hyperlink{rtss}{R\+T\+S\+S\+: Run Time Shader System}
\end{DoxyNote}
\begin{DoxyParagraph}{}
Format\+: alpha\+\_\+op\+\_\+ex $<$op$>$ $<$source1$>$ $<$source2$>$ \mbox{[}$<$manual\+Blend$>$\mbox{]} \mbox{[}$<$arg1$>$\mbox{]} \mbox{[}$<$arg2$>$\mbox{]}
\end{DoxyParagraph}
This works in exactly the same way as set\+Colour\+Operation\+Ex, except that the effect is applied to the level of alpha (i.\+e. transparency) of the texture rather than its colour. When the alpha of a texel (a pixel on a texture) is 1.\+0, it is opaque, whereas it is fully transparent if the alpha is 0.\+0. Please refer to the \hyperlink{class_ogre_1_1_texture_unit_state_a5f3994ce2f61c6c6fee6fe8f89c9e369}{Ogre\+::\+Texture\+Unit\+State\+::set\+Colour\+Operation\+Ex} method for more info. 
\begin{DoxyParams}{Parameters}
{\em op} & The operation to be used, e.\+g. modulate (multiply), add, subtract \\
\hline
{\em source1} & The source of the first alpha value to the operation e.\+g. texture alpha \\
\hline
{\em source2} & The source of the second alpha value to the operation e.\+g. current surface alpha \\
\hline
{\em arg1} & Manually supplied alpha value (only required if source1 = \hyperlink{group___materials_ggae2ad78de344f35307ce35157c175625ea9aad692ea2c7081237095c3ab4044f17}{Ogre\+::\+L\+B\+S\+\_\+\+M\+A\+N\+U\+AL}) \\
\hline
{\em arg2} & Manually supplied alpha value (only required if source2 = \hyperlink{group___materials_ggae2ad78de344f35307ce35157c175625ea9aad692ea2c7081237095c3ab4044f17}{Ogre\+::\+L\+B\+S\+\_\+\+M\+A\+N\+U\+AL}) \\
\hline
{\em manual\+Blend} & Manually supplied \textquotesingle{}blend\textquotesingle{} value -\/ only required for operations which require manual blend e.\+g. \hyperlink{group___materials_gga264ecab38a04d01e2c3158fa05ec1ee2adbe5957a946513e0f8be8c571f9b73fe}{Ogre\+::\+L\+B\+X\+\_\+\+B\+L\+E\+N\+D\+\_\+\+M\+A\+N\+U\+AL}\\
\hline
\end{DoxyParams}
\label{_env_005fmap}%
\label{_env_005fmap-1}%


\subsection*{env\+\_\+map}

Turns on/off texture coordinate effect that makes this layer an environment map. \begin{DoxyNote}{Note}
Only has an effect with the fixed-\/function pipeline or the \hyperlink{rtss}{R\+T\+S\+S\+: Run Time Shader System} 
\end{DoxyNote}
\begin{DoxyParagraph}{}
Format\+: env\+\_\+map $<$off$\vert$spherical$\vert$planar$\vert$cubic\+\_\+reflection$\vert$cubic\+\_\+normal$>$
\end{DoxyParagraph}
Environment maps make an object look reflective by using automatic texture coordinate generation depending on the relationship between the objects vertices or normals and the eye.


\begin{DoxyDescription}
\item[spherical ]

A spherical environment map. Requires a single texture which is either a fish-\/eye lens view of the reflected scene, or some other texture which looks good as a spherical map (a texture of glossy highlights is popular especially in car sims). This effect is based on the relationship between the eye direction and the vertex normals of the object, so works best when there are a lot of gradually changing normals, i.\+e. curved objects.


\item[planar ]

Similar to the spherical environment map, but the effect is based on the position of the vertices in the viewport rather than vertex normals. This effect is therefore useful for planar geometry (where a spherical env\+\_\+map would not look good because the normals are all the same) or objects without normals.


\item[cubic\+\_\+reflection ]

A more advanced form of reflection mapping which uses a group of 6 textures making up the inside of a cube, each of which is a view if the scene down each axis. Works extremely well in all cases but has a higher technical requirement from the card than spherical mapping. Requires that you bind a \href{#cubic_005ftexture}{\tt cubic\+\_\+texture} to this texture unit and use the ’combined\+U\+V\+W’ option.


\item[cubic\+\_\+normal ]

Generates 3D texture coordinates containing the camera space normal vector from the normal information held in the vertex data. Again, full use of this feature requires a \href{#cubic_005ftexture}{\tt cubic\+\_\+texture} with the ’combined\+U\+V\+W’ option.


\end{DoxyDescription}~\newline
 \begin{DoxyParagraph}{}
Default\+: env\+\_\+map off~\newline

\end{DoxyParagraph}
\label{_scroll}%
\label{_scroll-1}%


\subsection*{scroll}

Sets the translation offset of the texture, ie scrolls the texture. \begin{DoxyParagraph}{}
Format\+: scroll $<$u$>$ $<$v$>$
\end{DoxyParagraph}
This method sets the translation element of the texture transformation, and is easier to use than set\+Texture\+Transform if you are combining translation, scaling and rotation in your texture transformation. If you want to animate these values use \hyperlink{class_ogre_1_1_texture_unit_state_a45bd669bcc64ec417fe4208aa5cfd685}{Ogre\+::\+Texture\+Unit\+State\+::set\+Scroll\+Animation} 
\begin{DoxyParams}{Parameters}
{\em u} & The amount the texture should be moved horizontally (u direction). \\
\hline
{\em v} & The amount the texture should be moved vertically (v direction).\\
\hline
\end{DoxyParams}
\begin{DoxyNote}{Note}
if you’re using a vertex program this will have no effect unless you use the texture\+\_\+matrix auto-\/param.
\end{DoxyNote}
\label{_scroll_005fanim}%
\label{_scroll_005fanim-1}%


\subsection*{scroll\+\_\+anim}

Sets up an animated scroll for the texture layer. \begin{DoxyParagraph}{}
Format\+: scroll\+\_\+anim $<$u\+Speed$>$ $<$v\+Speed$>$~\newline

\end{DoxyParagraph}
Useful for creating constant scrolling effects on a texture layer (for varying scrolls, see \hyperlink{class_ogre_1_1_texture_unit_state_af56112cb1e6d144b8fd63b280d8ae350}{Ogre\+::\+Texture\+Unit\+State\+::set\+Transform\+Animation}). 
\begin{DoxyParams}{Parameters}
{\em u\+Speed} & The number of horizontal loops per second (+ve=moving right, -\/ve = moving left). \\
\hline
{\em v\+Speed} & The number of vertical loops per second (+ve=moving up, -\/ve= moving down).\\
\hline
\end{DoxyParams}
\begin{DoxyNote}{Note}
if you’re using a vertex program this will have no effect unless you use the texture\+\_\+matrix auto-\/param. \label{_rotate}%
\label{_rotate-1}%

\end{DoxyNote}
\subsection*{rotate}

Sets the anticlockwise rotation factor applied to texture coordinates.

\begin{DoxyParagraph}{}
Format\+: rotate $<$angle$>$
\end{DoxyParagraph}
This sets a fixed rotation angle -\/ if you wish to animate this, use \hyperlink{class_ogre_1_1_texture_unit_state_a72e3695b81f12b32762237c5de202dff}{Ogre\+::\+Texture\+Unit\+State\+::set\+Rotate\+Animation} 
\begin{DoxyParams}{Parameters}
{\em angle} & The angle of rotation (anticlockwise).\\
\hline
\end{DoxyParams}
\begin{DoxyNote}{Note}
if you’re using a vertex program this will have no effect unless you use the texture\+\_\+matrix auto-\/param.
\end{DoxyNote}
\label{_rotate_005fanim}%
\label{_rotate_005fanim-1}%


\subsection*{rotate\+\_\+anim}

Sets up an animated texture rotation for this layer.

\begin{DoxyParagraph}{}
Format\+: rotate\+\_\+anim $<$speed$>$
\end{DoxyParagraph}
Useful for constant rotations (for varying rotations, see \hyperlink{class_ogre_1_1_texture_unit_state_af56112cb1e6d144b8fd63b280d8ae350}{Ogre\+::\+Texture\+Unit\+State\+::set\+Transform\+Animation}). 
\begin{DoxyParams}{Parameters}
{\em speed} & The number of complete anticlockwise revolutions per second (use -\/ve for clockwise)\\
\hline
\end{DoxyParams}
\begin{DoxyNote}{Note}
if you’re using a vertex program this will have no effect unless you use the texture\+\_\+matrix auto-\/param.
\end{DoxyNote}
\label{_scale}%
\label{_scale-1}%


\subsection*{scale}

Sets the scaling factor applied to texture coordinates.

\begin{DoxyParagraph}{}
Format\+: scale $<$u\+Scale$>$ $<$v\+Scale$>$
\end{DoxyParagraph}
This method sets the scale element of the texture transformation, and is easier to use than set\+Texture\+Transform if you are combining translation, scaling and rotation in your texture transformation.

If you want to animate these values use \hyperlink{class_ogre_1_1_texture_unit_state_af56112cb1e6d144b8fd63b280d8ae350}{Ogre\+::\+Texture\+Unit\+State\+::set\+Transform\+Animation} 
\begin{DoxyParams}{Parameters}
{\em u\+Scale} & The value by which the texture is to be scaled horizontally. \\
\hline
{\em v\+Scale} & The value by which the texture is to be scaled vertically.\\
\hline
\end{DoxyParams}
\begin{DoxyNote}{Note}
if you’re using a vertex program this will have no effect unless you use the texture\+\_\+matrix auto-\/param.
\end{DoxyNote}
\label{_wave_005fxform}%
\label{_wave_005fxform-1}%


\subsection*{wave\+\_\+xform}

Sets up a general time-\/relative texture modification effect.

\begin{DoxyParagraph}{}
Format\+: wave\+\_\+xform $<$ttype$>$ $<$wave\+Type$>$ $<$base$>$ $<$frequency$>$ $<$phase$>$ $<$amplitude$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: wave\+\_\+xform scale\+\_\+x sine 1.\+0 0.\+2 0.\+0 5.\+0
\end{DoxyParagraph}
This can be called multiple times for different values of ttype, but only the latest effect applies if called multiple time for the same ttype. 
\begin{DoxyParams}{Parameters}
{\em ttype} & The type of transform, either translate (scroll), scale (stretch) or rotate (spin). \\
\hline
{\em wave\+Type} & The shape of the wave, see \hyperlink{group___general_gabf2e0412a783a6f708ca1a58abb45c1b}{Ogre\+::\+Waveform\+Type} enum for details. \\
\hline
{\em base} & The base value for the function (range of output = \{base, base + amplitude\}). \\
\hline
{\em frequency} & The speed of the wave in cycles per second. \\
\hline
{\em phase} & The offset of the start of the wave, e.\+g. 0.\+5 to start half-\/way through the wave. \\
\hline
{\em amplitude} & Scales the output so that instead of lying within 0..1 it lies within 0..1$\ast$amplitude for exaggerated effects.\\
\hline
\end{DoxyParams}
ttype is one of 
\begin{DoxyDescription}
\item[scroll\+\_\+x ]

Animate the u scroll value


\item[scroll\+\_\+y ]

Animate the v scroll value


\item[rotate ]

Animate the rotate value


\item[scale\+\_\+x ]

Animate the u scale value


\item[scale\+\_\+y ]

Animate the v scale value


\end{DoxyDescription}

wave\+Type is one of \hyperlink{group___general_gabf2e0412a783a6f708ca1a58abb45c1b}{Ogre\+::\+Waveform\+Type} without the {\ttfamily W\+F\+T\+\_\+} prefix. E.\+g. {\ttfamily W\+F\+T\+\_\+\+S\+Q\+U\+A\+RE} becomes {\ttfamily square}.

\begin{DoxyNote}{Note}
if you’re using a vertex program this will have no effect unless you use the texture\+\_\+matrix auto-\/param.
\end{DoxyNote}
\label{_transform}%
\label{_transform-1}%


\subsection*{transform}

This attribute allows you to specify a static 4x4 transformation matrix for the texture unit, thus replacing the individual scroll, rotate and scale attributes mentioned above. \begin{DoxyParagraph}{}
Format\+: transform m00 m01 m02 m03 m10 m11 m12 m13 m20 m21 m22 m23 m30 m31 m32 m33
\end{DoxyParagraph}
The indexes of the 4x4 matrix value above are expressed as m$<$row$>$$<$col$>$.

\begin{DoxyNote}{Note}
if you’re using a vertex program this will have no effect unless you use the texture\+\_\+matrix auto-\/param.
\end{DoxyNote}
\hypertarget{_material-_scripts_Declaring-Vertex_002fGeometry_002fFragment-Programs}{}\subsubsection{Declaring G\+P\+U Programs}\label{_material-_scripts_Declaring-Vertex_002fGeometry_002fFragment-Programs}
In order to use a vertex, geometry or fragment program in your materials (See \hyperlink{_high-level-_programs_Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass}{Using Vertex/\+Geometry/\+Fragment Programs in a Pass}), you first have to define them. A single program definition can be used by any number of materials, the only prerequisite is that a program must be defined before being referenced in the pass section of a material.

The definition of a program can either be embedded in the .material script itself (in which case it must precede any references to it in the script), or if you wish to use the same program across multiple .material files, you can define it in an external .program script. You define the program in exactly the same way whether you use a .program script or a .material script, the only difference is that all .program scripts are guaranteed to have been parsed before {\bfseries all} .material scripts, so you can guarantee that your program has been defined before any .material script that might use it. Just like .material scripts, .program scripts will be read from any location which is on your resource path, and you can define many programs in a single script.

Vertex, geometry and fragment programs can be low-\/level (i.\+e. assembler code written to the specification of a given low level syntax such as vs\+\_\+1\+\_\+1 or arbfp1) or high-\/level such as Direct\+X9 H\+L\+SL, Open GL Shader Language, or n\+Vidia’s Cg language (See \hyperlink{High-level-Programs}{High-\/level Programs}). High level languages give you a number of advantages, such as being able to write more intuitive code, and possibly being able to target multiple architectures in a single program (for example, the same Cg program might be able to be used in both D3D and GL, whilst the equivalent low-\/level programs would require separate techniques, each targeting a different A\+PI). High-\/level programs also allow you to use named parameters instead of simply indexed ones, although parameters are not defined here, they are used in the Pass.

Here is an example of a definition of a low-\/level vertex program\+:


\begin{DoxyCode}
vertex\_program myVertexProgram \textcolor{keyword}{asm}
\{
    source myVertexProgram.asm 
    syntax vs\_1\_1
\}
\end{DoxyCode}


As you can see, that’s very simple, and defining a fragment or geometry program is exactly the same, just with vertex\+\_\+program replaced with fragment\+\_\+program or geometry\+\_\+program, respectively. You give the program a name in the header, followed by the word ’asm’ to indicate that this is a low-\/level program. Inside the braces, you specify where the source is going to come from (and this is loaded from any of the resource locations as with other media), and also indicate the syntax being used. You might wonder why the syntax specification is required when many of the assembler syntaxes have a header identifying them anyway -\/ well the reason is that the engine needs to know what syntax the program is in before reading it, because during compilation of the material, we want to skip programs which use an unsupportable syntax quickly, without loading the program first.

The current supported syntaxes are\+:


\begin{DoxyDescription}
\item[vs\+\_\+1\+\_\+1 ]

This is one of the DirectX vertex shader assembler syntaxes. ~\newline
 Supported on cards from\+: A\+TI Radeon 8500, n\+Vidia Ge\+Force 3 ~\newline



\item[vs\+\_\+2\+\_\+0 ]

Another one of the DirectX vertex shader assembler syntaxes. ~\newline
 Supported on cards from\+: A\+TI Radeon 9600, n\+Vidia Ge\+Force FX 5 series ~\newline



\item[vs\+\_\+2\+\_\+x ]

Another one of the DirectX vertex shader assembler syntaxes. ~\newline
 Supported on cards from\+: A\+TI Radeon X series, n\+Vidia Ge\+Force FX 6 series ~\newline



\item[vs\+\_\+3\+\_\+0 ]

Another one of the DirectX vertex shader assembler syntaxes. ~\newline
 Supported on cards from\+: A\+TI Radeon HD 2000+, n\+Vidia Ge\+Force FX 6 series


\item[arbvp1 ]

This is the Open\+GL standard assembler format for vertex programs. It’s roughly equivalent to DirectX vs\+\_\+1\+\_\+1.


\item[vp20 ]

This is an n\+Vidia-\/specific Open\+GL vertex shader syntax which is a superset of vs 1.\+1. A\+TI Radeon HD 2000+ also supports it.


\item[vp30 ]

Another n\+Vidia-\/specific Open\+GL vertex shader syntax. It is a superset of vs 2.\+0, which is supported on n\+Vidia Ge\+Force FX 5 series and higher. A\+TI Radeon HD 2000+ also supports it.


\item[vp40 ]

Another n\+Vidia-\/specific Open\+GL vertex shader syntax. It is a superset of vs 3.\+0, which is supported on n\+Vidia Ge\+Force FX 6 series and higher.


\item[ps\+\_\+1\+\_\+1, ps\+\_\+1\+\_\+2, ps\+\_\+1\+\_\+3 ]

DirectX pixel shader (i.\+e. fragment program) assembler syntax. ~\newline
 Supported on cards from\+: A\+TI Radeon 8500, n\+Vidia Ge\+Force 3 ~\newline
 \begin{DoxyNote}{Note}
for A\+TI 8500, 9000, 9100, 9200 hardware, this profile can also be used in Open\+GL. The A\+TI 8500 to 9200 do not support arbfp1 but do support atifs extension in Open\+GL which is very similar in function to ps\+\_\+1\+\_\+4 in DirectX. \hyperlink{namespace_ogre}{Ogre} has a built in ps\+\_\+1\+\_\+x to atifs compiler that is automatically invoked when ps\+\_\+1\+\_\+x is used in Open\+GL on A\+TI hardware.
\end{DoxyNote}

\item[ps\+\_\+1\+\_\+4 ]

DirectX pixel shader (i.\+e. fragment program) assembler syntax. ~\newline
 Supported on cards from\+: A\+TI Radeon 8500, n\+Vidia Ge\+Force FX 5 series ~\newline
 \begin{DoxyNote}{Note}
for A\+TI 8500, 9000, 9100, 9200 hardware, this profile can also be used in Open\+GL. The A\+TI 8500 to 9200 do not support arbfp1 but do support atifs extension in Open\+GL which is very similar in function to ps\+\_\+1\+\_\+4 in DirectX. \hyperlink{namespace_ogre}{Ogre} has a built in ps\+\_\+1\+\_\+x to atifs compiler that is automatically invoked when ps\+\_\+1\+\_\+x is used in Open\+GL on A\+TI hardware.
\end{DoxyNote}

\item[ps\+\_\+2\+\_\+0 ]

DirectX pixel shader (i.\+e. fragment program) assembler syntax. ~\newline
 Supported cards\+: A\+TI Radeon 9600, n\+Vidia Ge\+Force FX 5 series~\newline



\item[ps\+\_\+2\+\_\+x ]

DirectX pixel shader (i.\+e. fragment program) assembler syntax. This is basically ps\+\_\+2\+\_\+0 with a higher number of instructions. ~\newline
 Supported cards\+: A\+TI Radeon X series, n\+Vidia Ge\+Force FX 6 series~\newline



\item[ps\+\_\+3\+\_\+0 ]

DirectX pixel shader (i.\+e. fragment program) assembler syntax. ~\newline
 Supported cards\+: A\+TI Radeon HD 2000+, n\+Vidia Ge\+Force F\+X6 series~\newline



\item[ps\+\_\+3\+\_\+x ]

DirectX pixel shader (i.\+e. fragment program) assembler syntax. ~\newline
 Supported cards\+: n\+Vidia Ge\+Force F\+X7 series~\newline



\item[arbfp1 ]

This is the Open\+GL standard assembler format for fragment programs. It’s roughly equivalent to ps\+\_\+2\+\_\+0, which means that not all cards that support basic pixel shaders under DirectX support arbfp1 (for example neither the Ge\+Force3 or Ge\+Force4 support arbfp1, but they do support ps\+\_\+1\+\_\+1).


\item[fp20 ]

This is an n\+Vidia-\/specific Open\+GL fragment syntax which is a superset of ps 1.\+3. It allows you to use the ’nvparse’ format for basic fragment programs. It actually uses N\+V\+\_\+texture\+\_\+shader and N\+V\+\_\+register\+\_\+combiners to provide functionality equivalent to Direct\+X’s ps\+\_\+1\+\_\+1 under GL, but only for n\+Vidia cards. However, since A\+TI cards adopted arbfp1 a little earlier than n\+Vidia, it is mainly n\+Vidia cards like the Ge\+Force3 and Ge\+Force4 that this will be useful for. You can find more information about nvparse at \href{http://developer.nvidia.com/object/nvparse.html}{\tt http\+://developer.\+nvidia.\+com/object/nvparse.\+html}.


\item[fp30 ]

Another n\+Vidia-\/specific Open\+GL fragment shader syntax. It is a superset of ps 2.\+0, which is supported on n\+Vidia Ge\+Force FX 5 series and higher. A\+TI Radeon HD 2000+ also supports it.


\item[fp40 ]

Another n\+Vidia-\/specific Open\+GL fragment shader syntax. It is a superset of ps 3.\+0, which is supported on n\+Vidia Ge\+Force FX 6 series and higher.


\item[gpu\+\_\+gp, gp4\+\_\+gp ]

An n\+Vidia-\/specific Open\+GL geometry shader syntax. ~\newline
 Supported cards\+: n\+Vidia Ge\+Force F\+X8 series~\newline



\item[glsles ]

Open\+GL Shading Language for Embedded Systems. It is a variant of G\+L\+SL, streamlined for low power devices. Supported cards\+: Power\+VR S\+GX series


\end{DoxyDescription}

You can get a definitive list of the syntaxes supported by the current card by calling Gpu\+Program\+Manager\+::get\+Singleton().get\+Supported\+Syntax().\hypertarget{_material-_scripts_Specifying-Named-Constants-for-Assembler-Shaders}{}\subsubsection{Specifying Named Constants for Assembler Shaders}\label{_material-_scripts_Specifying-Named-Constants-for-Assembler-Shaders}
Assembler shaders don’t have named constants (also called uniform parameters) because the language does not support them -\/ however if you for example decided to precompile your shaders from a high-\/level language down to assembler for performance or obscurity, you might still want to use the named parameters. Well, you actually can -\/ Gpu\+Named\+Constants which contains the named parameter mappings has a ’save’ method which you can use to write this data to disk, where you can reference it later using the manual\+\_\+named\+\_\+constants directive inside your assembler program declaration, e.\+g.


\begin{DoxyCode}
vertex\_program myVertexProgram \textcolor{keyword}{asm}
\{
    source myVertexProgram.asm 
    syntax vs\_1\_1
    manual\_named\_constants myVertexProgram.constants
\}
\end{DoxyCode}


In this case my\+Vertex\+Program.\+constants has been created by calling high\+Level\+Gpu\+Program-\/$>$get\+Named\+Constants().save(\char`\"{}my\+Vertex\+Program.\+constants\char`\"{}); sometime earlier as preparation, from the original high-\/level program. Once you’ve used this directive, you can use named parameters here even though the assembler program itself has no knowledge of them.\hypertarget{_material-_scripts_Default-Program-Parameters}{}\subsubsection{Default Program Parameters}\label{_material-_scripts_Default-Program-Parameters}
While defining a vertex, geometry or fragment program, you can also specify the default parameters to be used for materials which use it, unless they specifically override them. You do this by including a nested ’default\+\_\+params’ section, like so\+:


\begin{DoxyCode}
vertex\_program \hyperlink{namespace_ogre}{Ogre}/CelShadingVP cg
\{
    source Example\_CelShading.cg
    entry\_point main\_vp
    profiles vs\_1\_1 arbvp1

    default\_params
    \{
        param\_named\_auto lightPosition light\_position\_object\_space 0
        param\_named\_auto eyePosition camera\_position\_object\_space
        param\_named\_auto worldViewProj worldviewproj\_matrix
        param\_named shininess \textcolor{keywordtype}{float} 10 
    \}
\}
\end{DoxyCode}


The syntax of the parameter definition is exactly the same as when you define parameters when using programs, See \hyperlink{_high-level-_programs_Program-Parameter-Specification}{Parameter specification}. Defining default parameters allows you to avoid rebinding common parameters repeatedly (clearly in the above example, all but ’shininess’ are unlikely to change between uses of the program) which makes your material declarations shorter.\hypertarget{_material-_scripts_Declaring-Shared-Parameters}{}\subsubsection{Declaring Shared Parameters}\label{_material-_scripts_Declaring-Shared-Parameters}
Often, not every parameter you want to pass to a shader is unique to that program, and perhaps you want to give the same value to a number of different programs, and a number of different materials using that program. Shared parameter sets allow you to define a ’holding area’ for shared parameters that can then be referenced when you need them in particular shaders, while keeping the definition of that value in one place. To define a set of shared parameters, you do this\+:


\begin{DoxyCode}
shared\_params YourSharedParamsName
\{
    shared\_param\_named mySharedParam1 float4 0.1 0.2 0.3 0.4
    ...
\}
\end{DoxyCode}


As you can see, you need to use the keyword ’shared\+\_\+params’ and follow it with the name that you will use to identify these shared parameters. Inside the curly braces, you can define one parameter per line, in a way which is very similar to the \href{#param_005fnamed}{\tt param\+\_\+named} syntax. The definition of these lines is\+: \begin{DoxyParagraph}{}
Format\+: shared\+\_\+param\+\_\+name $<$param\+\_\+name$>$ $<$param\+\_\+type$>$ \mbox{[}$<$\mbox{[}array\+\_\+size\mbox{]}$>$\mbox{]} \mbox{[}$<$initial\+\_\+values$>$\mbox{]}
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em param\+\_\+name} & must be unique within the set \\
\hline
{\em param\+\_\+type} & can be any one of float, float2, float3, float4, int, int2, int3, int4, matrix2x2, matrix2x3, matrix2x4, matrix3x2, matrix3x3, matrix3x4, matrix4x2, matrix4x3 and matrix4x4. \\
\hline
{\em array\+\_\+size} & allows you to define arrays of param\+\_\+type should you wish, and if present must be a number enclosed in square brackets (and note, must be separated from the param\+\_\+type with whitespace). \\
\hline
{\em initial\+\_\+values} & If you wish, you can also initialise the parameters by providing a list of values.\\
\hline
\end{DoxyParams}
Once you have defined the shared parameters, you can reference them inside default\+\_\+params and params blocks using \href{#shared_005fparams_005fref}{\tt shared\+\_\+params\+\_\+ref}. You can also obtain a reference to them in your code via Gpu\+Program\+Manager\+::get\+Shared\+Parameters, and update the values for all instances using them.\hypertarget{_material-_scripts_Adding-new-Techniques_002c-Passes_002c-to-copied-materials_003a}{}\subsubsection{Adding new Techniques, Passes, to copied materials}\label{_material-_scripts_Adding-new-Techniques_002c-Passes_002c-to-copied-materials_003a}
If a new technique or pass needs to be added to a copied material then use a unique name for the technique or pass that does not exist in the parent material. Using an index for the name that is one greater than the last index in the parent will do the same thing. The new technique/pass will be added to the end of the techniques/passes copied from the parent material.

\begin{DoxyNote}{Note}
if passes or techniques aren’t given a name, they will take on a default name based on their index. For example the first pass has index 0 so its name will be 0.
\end{DoxyNote}
\hypertarget{_material-_scripts_Identifying-Texture-Units-to-override-values}{}\subsubsection{Identifying Texture Units to override values}\label{_material-_scripts_Identifying-Texture-Units-to-override-values}
A specific texture unit state (T\+US) can be given a unique name within a pass of a material so that it can be identified later in cloned materials that need to override specified texture unit states in the pass without declaring previous texture units. Using a unique name for a Texture unit in a pass of a cloned material adds a new texture unit at the end of the texture unit list for the pass.


\begin{DoxyCode}
material BumpMap2 : BumpMap1
\{
  technique ati8500
  \{
    pass 0
    \{
      texture\_unit NormalMap
      \{
        texture BumpyMetalNM.png
      \}
    \}
  \}
\}
\end{DoxyCode}
\hypertarget{_material-_scripts_Texture-Aliases}{}\subsubsection{Texture Aliases}\label{_material-_scripts_Texture-Aliases}
Texture aliases are useful for when only the textures used in texture units need to be specified for a cloned material. In the source material i.\+e. the original material to be cloned, each texture unit can be given a texture alias name. The cloned material in the script can then specify what textures should be used for each texture alias. Note that texture aliases are a more specific version of \href{#Script-Variables}{\tt Script Variables} which can be used to easily set other values.

Using texture aliases within texture units\+: \begin{DoxyParagraph}{}
Format\+: texture\+\_\+alias $<$name$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: $<$name$>$ will default to texture\+\_\+unit $<$name$>$ if set
\end{DoxyParagraph}

\begin{DoxyCode}
texture\_unit DiffuseTex
\{
  texture diffuse.jpg
\}
\end{DoxyCode}


texture\+\_\+alias defaults to Diffuse\+Tex.~\newline


Example\+: The base material to be cloned\+:~\newline



\begin{DoxyCode}
material TSNormalSpecMapping
\{
  technique GLSL
  \{
    pass 
    \{
      ambient 0.1 0.1 0.1
      diffuse 0.7 0.7 0.7
      specular 0.7 0.7 0.7 128

      vertex\_program\_ref GLSLDemo/OffsetMappingVS
      \{
        param\_named\_auto lightPosition light\_position\_object\_space 0
        param\_named\_auto eyePosition camera\_position\_object\_space
        param\_named textureScale \textcolor{keywordtype}{float} 1.0
      \}

      fragment\_program\_ref GLSLDemo/TSNormalSpecMappingFS 
      \{
        param\_named normalMap \textcolor{keywordtype}{int} 0
        param\_named diffuseMap \textcolor{keywordtype}{int} 1
        param\_named fxMap \textcolor{keywordtype}{int} 2
      \}

      \textcolor{comment}{// Normal map}
      texture\_unit NormalMap
      \{
        texture defaultNM.png
        tex\_coord\_set 0
        filtering trilinear
      \}

      \textcolor{comment}{// Base diffuse texture map}
      texture\_unit DiffuseMap
      \{
        texture defaultDiff.png
        filtering trilinear
        tex\_coord\_set 1
      \}

      \textcolor{comment}{// spec map for shininess}
      texture\_unit SpecMap
      \{
        texture defaultSpec.png
        filtering trilinear
        tex\_coord\_set 2
      \}

    \}
  \}

  technique HLSL\_DX9
  \{
    pass 
    \{

      vertex\_program\_ref FxMap\_HLSL\_VS
      \{
        param\_named\_auto worldViewProj\_matrix worldviewproj\_matrix 
        param\_named\_auto lightPosition light\_position\_object\_space 0
        param\_named\_auto eyePosition camera\_position\_object\_space
      \}

      fragment\_program\_ref FxMap\_HLSL\_PS 
      \{
        param\_named ambientColor float4 0.2 0.2 0.2 0.2
      \}

      \textcolor{comment}{// Normal map}
      texture\_unit 
      \{
        texture\_alias NormalMap
        texture defaultNM.png
        tex\_coord\_set 0
        filtering trilinear
      \}

      \textcolor{comment}{// Base diffuse texture map}
      texture\_unit 
      \{
        texture\_alias DiffuseMap
        texture defaultDiff.png
        filtering trilinear
        tex\_coord\_set 1
      \}

      \textcolor{comment}{// spec map for shininess}
      texture\_unit
      \{
        texture\_alias SpecMap
        texture defaultSpec.png
        filtering trilinear
        tex\_coord\_set 2
      \}

    \}
  \}
\}
\end{DoxyCode}


Note that the G\+L\+SL and H\+L\+SL techniques use the same textures. For each texture usage type a texture alias is given that describes what the texture is used for. So the first texture unit in the G\+L\+SL technique has the same alias as the T\+US in the H\+L\+SL technique since its the same texture used. Same goes for the second and third texture units.~\newline
 For demonstration purposes, the G\+L\+SL technique makes use of texture\+\_\+unit naming and therefore the texture\+\_\+alias name does not have to be set since it defaults to the texture unit name. So why not use the default all the time since its less typing? For most situations you can. Its when you clone a material that and then want to change the alias that you must use the texture\+\_\+alias command in the script. You cannot change the name of a texture\+\_\+unit in a cloned material so texture\+\_\+alias provides a facility to assign an alias name.

Now we want to clone the material but only want to change the textures used. We could copy and paste the whole material but if we decide to change the base material later then we also have to update the copied material in the script. With set\+\_\+texture\+\_\+alias, copying a material is very easy now. set\+\_\+texture\+\_\+alias is specified at the top of the material definition. All techniques using the specified texture alias will be effected by set\+\_\+texture\+\_\+alias.

\begin{DoxyParagraph}{}
Format\+: set\+\_\+texture\+\_\+alias $<$alias name$>$ $<$texture name$>$~\newline

\end{DoxyParagraph}

\begin{DoxyCode}
material fxTest : TSNormalSpecMapping
\{
  set\_texture\_alias NormalMap fxTestNMap.png
  set\_texture\_alias DiffuseMap fxTestDiff.png
  set\_texture\_alias SpecMap fxTestMap.png
\}
\end{DoxyCode}


The textures in both techniques in the child material will automatically get replaced with the new ones we want to use.

The same process can be done in code as long you set up the texture alias names so then there is no need to traverse technique/pass/\+T\+US to change a texture. You just call my\+Material\+Ptr-\/$>$apply\+Texture\+Aliases(my\+Alias\+Texture\+Name\+List) which will update all textures in all texture units that match the alias names in the map container reference you passed as a parameter.

You don’t have to supply all the textures in the copied material.~\newline



\begin{DoxyCode}
material fxTest2 : fxTest
\{
  set\_texture\_alias DiffuseMap fxTest2Diff.png
  set\_texture\_alias SpecMap fxTest2Map.png
\}
\end{DoxyCode}


Material fx\+Test2 only changes the diffuse and spec maps of material fx\+Test and uses the same normal map.

Another example\+:


\begin{DoxyCode}
material fxTest3 : TSNormalSpecMapping
\{
  set\_texture\_alias DiffuseMap fxTest2Diff.png
\}
\end{DoxyCode}


fx\+Test3 will end up with the default textures for the normal map and spec map setup in T\+S\+Normal\+Spec\+Mapping material but will have a different diffuse map. So your base material can define the default textures to use and then the child materials can override specific textures. \hypertarget{Compositor-Scripts}{}\subsection{Compositor Scripts}\label{Compositor-Scripts}
The compositor framework is a subsection of the O\+G\+RE A\+PI that allows you to easily define full screen post-\/processing effects. Compositor scripts offer you the ability to define compositor effects in a script which can be reused and modified easily, rather than having to use the A\+PI to define them. You still need to use code to instantiate a compositor against one of your visible viewports, but this is a much simpler process than actually defining the compositor itself.\hypertarget{_compositor-_scripts_Compositor-Fundamentals}{}\subsubsection{Compositor Fundamentals}\label{_compositor-_scripts_Compositor-Fundamentals}
Performing post-\/processing effects generally involves first rendering the scene to a texture, either in addition to or instead of the main window. Once the scene is in a texture, you can then pull the scene image into a fragment program and perform operations on it by rendering it through full screen quad. The target of this post processing render can be the main result (e.\+g. a window), or it can be another render texture so that you can perform multi-\/stage convolutions on the image. You can even ’ping-\/pong’ the render back and forth between a couple of render textures to perform convolutions which require many iterations, without using a separate texture for each stage. Eventually you’ll want to render the result to the final output, which you do with a full screen quad. This might replace the whole window (thus the main window doesn’t need to render the scene itself), or it might be a combinational effect.

So that we can discuss how to implement these techniques efficiently, a number of definitions are required\+:


\begin{DoxyDescription}
\item[Compositor ]

Definition of a fullscreen effect that can be applied to a user viewport. This is what you’re defining when writing compositor scripts as detailed in this section.


\item[Compositor Instance ]

An instance of a compositor as applied to a single viewport. You create these based on compositor definitions, See \href{#Applying-a-Compositor}{\tt Applying a Compositor}.


\item[Compositor Chain ]

It is possible to enable more than one compositor instance on a viewport at the same time, with one compositor taking the results of the previous one as input. This is known as a compositor chain. Every viewport which has at least one compositor attached to it has a compositor chain. See \href{#Applying-a-Compositor}{\tt Applying a Compositor}


\item[Target ]

This is a Render\+Target, i.\+e. the place where the result of a series of render operations is sent. A target may be the final output (and this is implicit, you don’t have to declare it), or it may be an intermediate render texture, which you declare in your script with the \href{#compositor_005ftexture}{\tt texture line}. A target which is not the output target has a defined size and pixel format which you can control.


\item[Output Target ]

As Target, but this is the single final result of all operations. The size and pixel format of this target cannot be controlled by the compositor since it is defined by the application using it, thus you don’t declare it in your script. However, you do declare a Target Pass for it, see below.


\item[Target Pass ]

A Target may be rendered to many times in the course of a composition effect. In particular if you ’ping pong’ a convolution between a couple of textures, you will have more than one Target Pass per Target. Target passes are declared in the script using a \href{#Compositor-Target-Passes}{\tt target or target\+\_\+output line}, the latter being the final output target pass, of which there can be only one.


\item[Pass ]

Within a Target Pass, there are one or more individual \href{#Compositor-Passes}{\tt passes}, which perform a very specific action, such as rendering the original scene (or pulling the result from the previous compositor in the chain), rendering a fullscreen quad, or clearing one or more buffers. Typically within a single target pass you will use the either a ’render scene’ pass or a ’render quad’ pass, not both. Clear can be used with either type.


\end{DoxyDescription}\hypertarget{_compositor-_scripts_Format-1}{}\subsubsection{Format}\label{_compositor-_scripts_Format-1}

\begin{DoxyCodeInclude}
\textcolor{comment}{// Black and white effect}
compositor B&W
\{
    technique
    \{
        \textcolor{comment}{// Temporary textures}
        texture rt0 target\_width target\_height \hyperlink{group___image_gga7e0353e7d36d4c2e8468641b7303d39ca0d5c9bdb0633c1849758fea566a2b754}{PF\_A8R8G8B8}

        target rt0
        \{
            \textcolor{comment}{// Render output from previous compositor (or original scene)}
            input previous
        \}

        target\_output
        \{
            \textcolor{comment}{// Start with clear output}
            input none
            \textcolor{comment}{// Draw a fullscreen quad with the black and white image}
            pass render\_quad
            \{
                \textcolor{comment}{// Renders a fullscreen quad with a material}
                material \hyperlink{namespace_ogre}{Ogre}/Compositor/BlackAndWhite
                input 0 rt0
            \}
        \}
    \}
\}
\end{DoxyCodeInclude}
 The major components of a compositor are the \href{#Compositor-Techniques}{\tt techniques}, the \href{#Compositor-Target-Passes}{\tt target passes} and the \href{#Compositor-Passes}{\tt passes}, which are covered in detail in the following sections.\hypertarget{_compositor-_scripts_Compositor-Techniques}{}\paragraph{Techniques}\label{_compositor-_scripts_Compositor-Techniques}
A compositor technique is much like a \hyperlink{_material-_scripts_Techniques}{material technique} in that it describes one approach to achieving the effect you’re looking for. A compositor definition can have more than one technique if you wish to provide some fallback should the hardware not support the technique you’d prefer to use. Techniques are evaluated for hardware support based on 2 things\+:


\begin{DoxyDescription}
\item[Material support ]

All \href{#Compositor-Passes}{\tt passes} that render a fullscreen quad use a material; for the technique to be supported, all of the materials referenced must have at least one supported material technique. If they don’t, the compositor technique is marked as unsupported and won’t be used.


\item[Texture format support ]

This one is slightly more complicated. When you request a \href{#compositor_005ftexture}{\tt texture} in your technique, you request a pixel format. Not all formats are natively supported by hardware, especially the floating point formats. However, in this case the hardware will typically downgrade the texture format requested to one that the hardware does support -\/ with compositor effects though, you might want to use a different approach if this is the case. So, when evaluating techniques, the compositor will first look for native support for the exact pixel format you’ve asked for, and will skip onto the next technique if it is not supported, thus allowing you to define other techniques with simpler pixel formats which use a different approach. If it doesn’t find any techniques which are natively supported, it tries again, this time allowing the hardware to downgrade the texture format and thus should find at least some support for what you’ve asked for.


\end{DoxyDescription}

As with material techniques, compositor techniques are evaluated in the order you define them in the script, so techniques declared first are preferred over those declared later.

Format\+: technique \{ \}

Techniques can have the following nested elements\+:


\begin{DoxyItemize}
\item \href{#compositor_005ftexture}{\tt texture}
\item \href{#compositor_005ftexture_005fref}{\tt texture\+\_\+ref}
\item \href{#compositor_005fscheme}{\tt scheme}
\item \href{#compositor_005flogic}{\tt compositor\+\_\+logic}
\item \href{#Compositor-Target-Passes}{\tt target}
\item \href{#Compositor-Target-Passes}{\tt target\+\_\+output}
\end{DoxyItemize}

\label{_compositor_005ftexture}%
\label{_texture-2}%


\subsection*{texture}

This declares a render texture for use in subsequent \href{#Compositor-Target-Passes}{\tt target passes}. \begin{DoxyParagraph}{}
Format\+: texture $<$Name$>$ $<$Width$>$ $<$Height$>$ $<$Pixel\+\_\+\+Format$>$ \mbox{[}$<$M\+RT Pixel\+\_\+\+Format2$>$\mbox{]} \mbox{[}$<$M\+RT Pixel\+\_\+\+FormatN$>$\mbox{]} \mbox{[}pooled\mbox{]} \mbox{[}gamma\mbox{]} \mbox{[}no\+\_\+fsaa\mbox{]} \mbox{[}depth\+\_\+pool $<$pool\+Id$>$\mbox{]} \mbox{[}$<$scope$>$\mbox{]}
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em Name} & A name to give the render texture, which must be unique within this compositor. This name is used to reference the texture in \href{#Compositor-Target-Passes}{\tt target passes}, when the texture is rendered to, and in \href{#Compositor-Passes}{\tt passes}, when the texture is used as input to a material rendering a fullscreen quad.\\
\hline
{\em Width} & \\
\hline
{\em Height} & The dimensions of the render texture. You can either specify a fixed width and height, or you can request that the texture is based on the physical dimensions of the viewport to which the compositor is attached. The options for the latter are ’target\+\_\+width’, ’target\+\_\+height’, ’target\+\_\+width\+\_\+scaled $<$factor$>$’ and ’target\+\_\+height\+\_\+scaled $<$factor$>$’ -\/ where ’factor’ is the amount by which you wish to multiply the size of the main target to derive the dimensions.\\
\hline
{\em Pixel\+\_\+\+Format} & The pixel format of the render texture. This affects how much memory it will take, what colour channels will be available, and what precision you will have within those channels. The available options are P\+F\+\_\+\+A8\+R8\+G8\+B8, P\+F\+\_\+\+R8\+G8\+B8\+A8, P\+F\+\_\+\+R8\+G8\+B8, P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+\+R\+G\+BA, P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+\+R\+GB, P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+R, P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+\+R\+G\+BA, P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+\+R\+GB, and P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+R.\\
\hline
{\em pooled} & If present, this directive makes this texture ’pooled’ among compositor instances, which can save some memory.\\
\hline
{\em gamma} & If present, this directive means that s\+R\+GB gamma correction will be enabled on writes to this texture. You should remember to include the opposite s\+R\+GB conversion when you read this texture back in another material, such as a quad. This option will automatically enabled if you use a render\+\_\+scene pass on this texture and the viewport on which the compositor is based has s\+R\+GB write support enabled.\\
\hline
{\em no\+\_\+fsaa} & If present, this directive disables the use of anti-\/aliasing on this texture. F\+S\+AA is only used if this texture is subject to a render\+\_\+scene pass and F\+S\+AA was enabled on the original viewport on which this compositor is based; this option allows you to override it and disable the F\+S\+AA if you wish.\\
\hline
{\em depth\+\_\+pool} & When present, this directive has to be followed by an integer. This directive is unrelated to the \char`\"{}pooled\char`\"{} directive. This one sets from which Depth buffer pool the depth buffer will be chosen from. All R\+Ts from all compositors (including render windows if the render system A\+PI allows it) with the same pool ID share the same depth buffers (following the rules of the current render system A\+P\+Is, (check Render\+System\+Capabilities flags to find the rules). When the pool ID is 0, no depth buffer is used. This can be helpful for passes that don’t require a Depth buffer at all, potentially saving performance and memory. Default value is 1.\\
\hline
{\em scope} & If present, this directive sets the scope for the texture for being accessed by other compositors using the \href{#compositor_005ftexture_005fref}{\tt texture\+\_\+ref} directive. There are three options \+: ’local\+\_\+scope’ (which is also the default) means that only the compositor defining the texture can access it. ’chain\+\_\+scope’ means that the compositors after this compositor in the chain can reference its textures, and ’global\+\_\+scope’ means that the entire application can access the texture. This directive also affects the creation of the textures (global textures are created once and thus can’t be used with the pooled directive, and can’t rely on viewport size).\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Example\+: texture rt0 512 512 P\+F\+\_\+\+R8\+G8\+B8\+A8~\newline
 Example\+: texture rt1 target\+\_\+width target\+\_\+height P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+\+R\+GB
\end{DoxyParagraph}
You can in fact repeat this element if you wish. If you do so, that means that this render texture becomes a Multiple Render Target (M\+RT), when the G\+PU writes to multiple textures at once. It is imperative that if you use M\+RT that the shaders that render to it render to A\+LL the targets. Not doing so can cause undefined results. It is also important to note that although you can use different pixel formats for each target in a M\+RT, each one should have the same total bit depth since most cards do not support independent bit depths. If you try to use this feature on cards that do not support the number of M\+R\+Ts you’ve asked for, the technique will be skipped (so you ought to write a fallback technique).

\begin{DoxyParagraph}{}
Example \+: texture mrt\+\_\+output target\+\_\+width target\+\_\+height P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+\+R\+G\+BA P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+\+R\+G\+BA chain\+\_\+scope
\end{DoxyParagraph}
\label{_compositor_005ftexture_005fref}%
\label{_texture_005fref}%


\subsection*{texture\+\_\+ref}

This declares a reference of a texture from another compositor to be used in this compositor.

\begin{DoxyParagraph}{}
Format\+: texture\+\_\+ref $<$Local\+\_\+\+Name$>$ $<$Reference\+\_\+\+Compositor$>$ $<$Reference\+\_\+\+Texture\+\_\+\+Name$>$
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em Local\+\_\+\+Name} & A name to give the referenced texture, which must be unique within this compositor. This name is used to reference the texture in \href{#Compositor-Target-Passes}{\tt target passes}, when the texture is rendered to, and in \href{#Compositor-Passes}{\tt passes}, when the texture is used as input to a material rendering a fullscreen quad.\\
\hline
{\em Reference\+\_\+\+Compositor} & The name of the compositor that we are referencing a texture from\\
\hline
{\em Reference\+\_\+\+Texture\+\_\+\+Name} & The name of the texture in the compositor that we are referencing\\
\hline
\end{DoxyParams}
Make sure that the texture being referenced is scoped accordingly (either chain or global scope) and placed accordingly during chain creation (if referencing a chain-\/scoped texture, the compositor must be present in the chain and placed before the compositor referencing it).

\begin{DoxyParagraph}{}
Example \+: texture\+\_\+ref G\+Buffer G\+Buffer\+Compositor mrt\+\_\+output
\end{DoxyParagraph}
\label{_compositor_005fscheme}%
\label{_scheme-2}%


\subsection*{scheme}

This gives a compositor technique a scheme name, allowing you to manually switch between different techniques for this compositor when instantiated on a viewport by calling Compositor\+Instance\+::set\+Scheme.

\begin{DoxyParagraph}{}
Format\+: material\+\_\+scheme $<$Name$>$
\end{DoxyParagraph}
\label{_compositor_005flogic}%
\label{_compositor_005flogic-1}%


\subsection*{compositor\+\_\+logic}

This connects between a compositor and code that it requires in order to function correctly. When an instance of this compositor will be created, the compositor logic will be notified and will have the chance to prepare the compositor’s operation (for example, adding a listener).

\begin{DoxyParagraph}{}
Format\+: compositor\+\_\+logic $<$Name$>$
\end{DoxyParagraph}
Registration of compositor logics is done by name through Compositor\+Manager\+::register\+Compositor\+Logic.\hypertarget{_compositor-_scripts_Compositor-Target-Passes}{}\paragraph{Target Passes}\label{_compositor-_scripts_Compositor-Target-Passes}
A target pass is the action of rendering to a given target, either a render texture or the final output. You can update the same render texture multiple times by adding more than one target pass to your compositor script -\/ this is very useful for ’ping pong’ renders between a couple of render textures to perform complex convolutions that cannot be done in a single render, such as blurring.

There are two types of target pass, the sort that updates a render texture\+: Format\+: target $<$Name$>$ \{ \} ... and the sort that defines the final output render\+: Format\+: target\+\_\+output \{ \}

The contents of both are identical, the only real difference is that you can only have a single target\+\_\+output entry, whilst you can have many target entries. Here are the attributes you can use in a ’target’ or ’target\+\_\+output’ section of a .compositor script\+:


\begin{DoxyItemize}
\item \href{#compositor_005ftarget_005finput}{\tt input}
\item \href{#only_005finitial}{\tt only\+\_\+initial}
\item \href{#visibility_005fmask}{\tt visibility\+\_\+mask}
\item \href{#compositor_005flod_005fbias}{\tt lod\+\_\+bias}
\item \href{#material_005fscheme}{\tt material\+\_\+scheme}
\item \href{#compositor_005fshadows}{\tt shadows}
\item \href{#Compositor-Passes}{\tt pass}
\end{DoxyItemize}

\label{_Attribute-Descriptions-2}%


\section*{Attribute Descriptions}

\label{_compositor_005ftarget_005finput}%
\label{_input}%


\subsection*{input}

Sets input mode of the target, which tells the target pass what is pulled in before any of its own passes are rendered.

\begin{DoxyParagraph}{}
Format\+: input (none $\vert$ previous) 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: input none
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em none} & The target will have nothing as input, all the contents of the target must be generated using its own passes. Note this does not mean the target will be empty, just no data will be pulled in. For it to truly be blank you’d need a ’clear’ pass within this target.\\
\hline
{\em previous} & The target will pull in the previous contents of the viewport. This will be either the original scene if this is the first compositor in the chain, or it will be the output from the previous compositor in the chain if the viewport has multiple compositors enabled.\\
\hline
\end{DoxyParams}


\label{_only_005finitial}%
\label{_only_005finitial-1}%


\subsection*{only\+\_\+initial}

If set to on, this target pass will only execute once initially after the effect has been enabled. This could be useful to perform once-\/off renders, after which the static contents are used by the rest of the compositor.

\begin{DoxyParagraph}{}
Format\+: only\+\_\+initial (on $\vert$ off) 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: only\+\_\+initial off
\end{DoxyParagraph}
\label{_visibility_005fmask}%
\label{_visibility_005fmask-1}%


\subsection*{visibility\+\_\+mask}

Sets the visibility mask for any render\+\_\+scene passes performed in this target pass. This is a bitmask (although it must be specified as decimal, not hex) and maps to Viewport\+::set\+Visibility\+Mask. \begin{DoxyParagraph}{}
Format\+: visibility\+\_\+mask $<$mask$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: visibility\+\_\+mask 4294967295
\end{DoxyParagraph}
\label{_compositor_005flod_005fbias}%
\label{_lod_005fbias}%


\subsection*{lod\+\_\+bias}

Set the scene L\+OD bias for any render\+\_\+scene passes performed in this target pass. The default is 1.\+0, everything below that means lower quality, higher means higher quality. \begin{DoxyParagraph}{}
Format\+: lod\+\_\+bias $<$lodbias$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: lod\+\_\+bias 1.\+0
\end{DoxyParagraph}
\label{_compositor_005fshadows}%
\label{_shadows}%


\subsection*{shadows}

Sets whether shadows should be rendered during any render\+\_\+scene pass performed in this target pass.

\begin{DoxyParagraph}{}
Format\+: shadows (on $\vert$ off) 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: shadows on
\end{DoxyParagraph}
\label{_material_005fscheme}%
\label{_material_005fscheme-1}%


\subsection*{material\+\_\+scheme}

If set, indicates the material scheme to use for any render\+\_\+scene pass. Useful for performing special-\/case rendering effects.

\begin{DoxyParagraph}{}
Format\+: material\+\_\+scheme $<$scheme name$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: None
\end{DoxyParagraph}
\hypertarget{_compositor-_scripts_Compositor-Passes}{}\paragraph{Compositor Passes}\label{_compositor-_scripts_Compositor-Passes}
A pass is a single rendering action to be performed in a target pass. \begin{DoxyParagraph}{}
Format\+: ’pass’ (render\+\_\+quad $\vert$ clear $\vert$ stencil $\vert$ render\+\_\+scene $\vert$ render\+\_\+custom) \mbox{[}custom name\mbox{]} \{ \}
\end{DoxyParagraph}
There are four types of pass\+:


\begin{DoxyDescription}
\item[clear ]

This kind of pass sets the contents of one or more buffers in the target to a fixed value. So this could clear the colour buffer to a fixed colour, set the depth buffer to a certain set of contents, fill the stencil buffer with a value, or any combination of the above.


\item[stencil ]

This kind of pass configures stencil operations for the subsequent passes. It can set the stencil compare function, operations and reference values for you to perform your own stencil effects.


\item[render\+\_\+scene ]

This kind of pass performs a regular rendering of the scene. It will use the \href{#visibility_005fmask}{\tt visibility\+\_\+mask}, \href{#compositor_005flod_005fbias}{\tt lod\+\_\+bias}, and \href{#material_005fscheme}{\tt material\+\_\+scheme} from the parent target pass.


\item[render\+\_\+quad ]

This kind of pass renders a quad over the entire render target, using a given material. You will undoubtedly want to pull in the results of other target passes into this operation to perform fullscreen effects.


\item[render\+\_\+custom ]

This kind of pass is just a callback to user code for the composition pass specified in the custom name (and registered via Compositor\+Manager\+::register\+Custom\+Composition\+Pass) and allows the user to create custom render operations for more advanced effects. This is the only pass type that requires the custom name parameter.


\end{DoxyDescription}

Here are the attributes you can use in a ’pass’ section of a .compositor script\+:

\label{_Available-Pass-Attributes}%


\section*{Available Pass Attributes}


\begin{DoxyItemize}
\item \href{#material}{\tt material}
\item \href{#compositor_005fpass_005finput}{\tt input}
\item \href{#compositor_005fpass_005fidentifier}{\tt identifier}
\item \href{#first_005frender_005fqueue}{\tt first\+\_\+render\+\_\+queue}
\item \href{#last_005frender_005fqueue}{\tt last\+\_\+render\+\_\+queue}
\item \href{#compositor_005fpass_005fmaterial_005fscheme}{\tt material\+\_\+scheme}
\item \href{#compositor_005fclear}{\tt clear}
\item \href{#compositor_005fstencil}{\tt stencil}
\end{DoxyItemize}

\label{_material}%
\label{_material-1}%


\subsection*{material}

For passes of type ’render\+\_\+quad’, sets the material used to render the quad. You will want to use shaders in this material to perform fullscreen effects, and use the \href{#compositor_005fpass_005finput}{\tt input} attribute to map other texture targets into the texture bindings needed by this material. Format\+: material $<$Name$>$

\label{_compositor_005fpass_005finput}%
\label{_input-1}%


\subsection*{input}

For passes of type ’render\+\_\+quad’, this is how you map one or more local render textures (See \href{#compositor_005ftexture}{\tt compositor\+\_\+texture}) into the material you’re using to render the fullscreen quad. To bind more than one texture, repeat this attribute with different sampler indexes.

\begin{DoxyParagraph}{}
Format\+: input $<$sampler$>$ $<$Name$>$ \mbox{[}$<$M\+R\+T\+Index$>$\mbox{]}
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em sampler} & The texture sampler to set, must be a number in the range \mbox{[}0, O\+G\+R\+E\+\_\+\+M\+A\+X\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+L\+A\+Y\+E\+R\+S-\/1\mbox{]}. \\
\hline
{\em Name} & The name of the local render texture to bind, as declared in \href{#compositor_005ftexture}{\tt compositor\+\_\+texture} and rendered to in one or more \href{#Compositor-Target-Passes}{\tt target pass}. \\
\hline
{\em M\+R\+T\+Index} & If the local texture that you’re referencing is a Multiple Render Target (M\+RT), this identifies the surface from the M\+RT that you wish to reference (0 is the first surface, 1 the second etc).\\
\hline
\end{DoxyParams}
\begin{DoxyParagraph}{}
Example\+: input 0 rt0
\end{DoxyParagraph}
\label{_compositor_005fpass_005fidentifier}%
\label{_identifier}%


\subsection*{identifier}

Associates a numeric identifier with the pass. This is useful for registering a listener with the compositor (Compositor\+Instance\+::add\+Listener), and being able to identify which pass it is that’s being processed when you get events regarding it. Numbers between 0 and 2$^\wedge$32 are allowed.

\begin{DoxyParagraph}{}
Format\+: identifier $<$number$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: identifier 99945 Default\+: identifier 0
\end{DoxyParagraph}
\label{_first_005frender_005fqueue}%
\label{_first_005frender_005fqueue-1}%


\subsection*{first\+\_\+render\+\_\+queue}

For passes of type ’render\+\_\+scene’, this sets the first render queue id that is included in the render. Defaults to the value of R\+E\+N\+D\+E\+R\+\_\+\+Q\+U\+E\+U\+E\+\_\+\+S\+K\+I\+E\+S\+\_\+\+E\+A\+R\+LY. \begin{DoxyParagraph}{}
Format\+: first\+\_\+render\+\_\+queue $<$id$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: first\+\_\+render\+\_\+queue 0
\end{DoxyParagraph}
\label{_last_005frender_005fqueue}%
\label{_last_005frender_005fqueue-1}%


\subsection*{last\+\_\+render\+\_\+queue}

For passes of type ’render\+\_\+scene’, this sets the last render queue id that is included in the render. Defaults to the value of R\+E\+N\+D\+E\+R\+\_\+\+Q\+U\+E\+U\+E\+\_\+\+S\+K\+I\+E\+S\+\_\+\+L\+A\+TE. \begin{DoxyParagraph}{}
Format\+: last\+\_\+render\+\_\+queue $<$id$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: last\+\_\+render\+\_\+queue 95
\end{DoxyParagraph}
\label{_compositor_005fpass_005fmaterial_005fscheme}%
\label{_material_005fscheme-2}%


\subsection*{material\+\_\+scheme}

If set, indicates the material scheme to use for this pass only. Useful for performing special-\/case rendering effects. This will overwrite the scheme if set at the target scope as well. \begin{DoxyParagraph}{}
Format\+: material\+\_\+scheme $<$scheme name$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: None
\end{DoxyParagraph}
\hypertarget{_compositor-_scripts_Clear-Section}{}\subsubsection{Clear Section}\label{_compositor-_scripts_Clear-Section}
For passes of type ’clear’, this section defines the buffer clearing parameters. Format\+: clear \{ \}

Here are the attributes you can use in a ’clear’ section of a .compositor script\+:


\begin{DoxyItemize}
\item \href{#compositor_005fclear_005fbuffers}{\tt buffers}
\item \href{#compositor_005fclear_005fcolour_005fvalue}{\tt colour\+\_\+value}
\item \href{#compositor_005fclear_005fdepth_005fvalue}{\tt depth\+\_\+value}
\item \href{#compositor_005fclear_005fstencil_005fvalue}{\tt stencil\+\_\+value} \label{_compositor_005fclear_005fbuffers}%
\label{_buffers}%

\end{DoxyItemize}

\subsection*{buffers}

Sets the buffers cleared by this pass.

\begin{DoxyParagraph}{}
Format\+: buffers \mbox{[}colour\mbox{]} \mbox{[}depth\mbox{]} \mbox{[}stencil\mbox{]} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: buffers colour depth
\end{DoxyParagraph}
\label{_compositor_005fclear_005fcolour_005fvalue}%
\label{_colour_005fvalue}%


\subsection*{colour\+\_\+value}

Set the colour used to fill the colour buffer by this pass, if the colour buffer is being cleared (\href{#compositor_005fclear_005fbuffers}{\tt buffers}). \begin{DoxyParagraph}{}
Format\+: colour\+\_\+value $<$red$>$ $<$green$>$ $<$blue$>$ $<$alpha$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: colour\+\_\+value 0 0 0 0
\end{DoxyParagraph}
\label{_compositor_005fclear_005fdepth_005fvalue}%
\label{_depth_005fvalue}%


\subsection*{depth\+\_\+value}

Set the depth value used to fill the depth buffer by this pass, if the depth buffer is being cleared (\href{#compositor_005fclear_005fbuffers}{\tt buffers}). \begin{DoxyParagraph}{}
Format\+: depth\+\_\+value $<$depth$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: depth\+\_\+value 1.\+0
\end{DoxyParagraph}
\label{_compositor_005fclear_005fstencil_005fvalue}%
\label{_stencil_005fvalue}%


\subsection*{stencil\+\_\+value}

Set the stencil value used to fill the stencil buffer by this pass, if the stencil buffer is being cleared (\href{#compositor_005fclear_005fbuffers}{\tt buffers}). \begin{DoxyParagraph}{}
Format\+: stencil\+\_\+value $<$value$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: stencil\+\_\+value 0.\+0
\end{DoxyParagraph}
\hypertarget{_compositor-_scripts_Stencil-Section}{}\subsubsection{Stencil Section}\label{_compositor-_scripts_Stencil-Section}
For passes of type ’stencil’, this section defines the stencil operation parameters.

Format\+: stencil \{ \}

Here are the attributes you can use in a ’stencil’ section of a .compositor script\+:


\begin{DoxyItemize}
\item \href{#compositor_005fstencil_005fcheck}{\tt check}
\item \href{#compositor_005fstencil_005fcomp_005ffunc}{\tt comp\+\_\+func}
\item \href{#compositor_005fstencil_005fref_005fvalue}{\tt ref\+\_\+value}
\item \href{#compositor_005fstencil_005fmask}{\tt mask}
\item \href{#compositor_005fstencil_005ffail_005fop}{\tt fail\+\_\+op}
\item \href{#compositor_005fstencil_005fdepth_005ffail_005fop}{\tt depth\+\_\+fail\+\_\+op}
\item \href{#compositor_005fstencil_005fpass_005fop}{\tt pass\+\_\+op}
\item \href{#compositor_005fstencil_005ftwo_005fsided}{\tt two\+\_\+sided} \label{_compositor_005fstencil_005fcheck}%
\label{_check}%

\end{DoxyItemize}

\subsection*{check}

Enables or disables the stencil check, thus enabling the use of the rest of the features in this section. The rest of the options in this section do nothing if the stencil check is off. \begin{DoxyParagraph}{}
Format\+: check (on $\vert$ off)
\end{DoxyParagraph}
\label{_compositor_005fstencil_005fcomp_005ffunc}%
\label{_comp_005ffunc}%


\subsection*{comp\+\_\+func}

Sets the function used to perform the following comparison\+: (ref\+\_\+value \& mask) comp\+\_\+func (Stencil Buffer Value \& mask)

What happens as a result of this comparison will be one of 3 actions on the stencil buffer, depending on whether the test fails, succeeds but with the depth buffer check still failing, or succeeds with the depth buffer check passing too. You set the actions in the \href{#compositor_005fstencil_005ffail_005fop}{\tt fail\+\_\+op}, \href{#compositor_005fstencil_005fdepth_005ffail_005fop}{\tt depth\+\_\+fail\+\_\+op} and \href{#compositor_005fstencil_005fpass_005fop}{\tt pass\+\_\+op} respectively. If the stencil check fails, no colour or depth are written to the frame buffer. \begin{DoxyParagraph}{}
Format\+: comp\+\_\+func (always\+\_\+fail $\vert$ always\+\_\+pass $\vert$ less $\vert$ less\+\_\+equal $\vert$ not\+\_\+equal $\vert$ greater\+\_\+equal $\vert$ greater) 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: comp\+\_\+func always\+\_\+pass
\end{DoxyParagraph}
\label{_compositor_005fstencil_005fref_005fvalue}%
\label{_ref_005fvalue}%


\subsection*{ref\+\_\+value}

Sets the reference value used to compare with the stencil buffer as described in \href{#compositor_005fstencil_005fcomp_005ffunc}{\tt comp\+\_\+func}. \begin{DoxyParagraph}{}
Format\+: ref\+\_\+value $<$value$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: ref\+\_\+value 0.\+0
\end{DoxyParagraph}
\label{_compositor_005fstencil_005fmask}%
\label{_mask}%


\subsection*{mask}

Sets the mask used to compare with the stencil buffer as described in \href{#compositor_005fstencil_005fcomp_005ffunc}{\tt comp\+\_\+func}. \begin{DoxyParagraph}{}
Format\+: mask $<$value$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: mask 4294967295
\end{DoxyParagraph}
\label{_compositor_005fstencil_005ffail_005fop}%
\label{_fail_005fop}%


\subsection*{fail\+\_\+op}

Sets what to do with the stencil buffer value if the result of the stencil comparison (\href{#compositor_005fstencil_005fcomp_005ffunc}{\tt comp\+\_\+func}) and depth comparison is that both fail. \begin{DoxyParagraph}{}
Format\+: fail\+\_\+op (keep $\vert$ zero $\vert$ replace $\vert$ increment $\vert$ decrement $\vert$ increment\+\_\+wrap $\vert$ decrement\+\_\+wrap $\vert$ invert) 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: depth\+\_\+fail\+\_\+op keep These actions mean\+:
\end{DoxyParagraph}

\begin{DoxyDescription}
\item[keep ]

Leave the stencil buffer unchanged.


\item[zero ]

Set the stencil value to zero.


\item[replace ]

Set the stencil value to the reference value.


\item[increment ]

Add one to the stencil value, clamping at the maximum value.


\item[decrement ]

Subtract one from the stencil value, clamping at 0.


\item[increment\+\_\+wrap ]

Add one to the stencil value, wrapping back to 0 at the maximum.


\item[decrement\+\_\+wrap ]

Subtract one from the stencil value, wrapping to the maximum below 0.


\item[invert ]

invert the stencil value.


\end{DoxyDescription}\label{_compositor_005fstencil_005fdepth_005ffail_005fop}%
\label{_depth_005ffail_005fop}%


\subsection*{depth\+\_\+fail\+\_\+op}

Sets what to do with the stencil buffer value if the result of the stencil comparison (\href{#compositor_005fstencil_005fcomp_005ffunc}{\tt comp\+\_\+func}) passes but the depth comparison fails.

\begin{DoxyParagraph}{}
Format\+: depth\+\_\+fail\+\_\+op (keep $\vert$ zero $\vert$ replace $\vert$ increment $\vert$ decrement $\vert$ increment\+\_\+wrap $\vert$ decrement\+\_\+wrap $\vert$ invert) 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: depth\+\_\+fail\+\_\+op keep
\end{DoxyParagraph}
\label{_compositor_005fstencil_005fpass_005fop}%
\label{_pass_005fop}%


\subsection*{pass\+\_\+op}

Sets what to do with the stencil buffer value if the result of the stencil comparison (\href{#compositor_005fstencil_005fcomp_005ffunc}{\tt comp\+\_\+func}) and the depth comparison pass. \begin{DoxyParagraph}{}
Format\+: pass\+\_\+op (keep $\vert$ zero $\vert$ replace $\vert$ increment $\vert$ decrement $\vert$ increment\+\_\+wrap $\vert$ decrement\+\_\+wrap $\vert$ invert) 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: pass\+\_\+op keep
\end{DoxyParagraph}
\label{_compositor_005fstencil_005ftwo_005fsided}%
\label{_two_005fsided}%


\subsection*{two\+\_\+sided}

Enables or disables two-\/sided stencil operations, which means the inverse of the operations applies to back-\/facing polygons. \begin{DoxyParagraph}{}
Format\+: two\+\_\+sided (on $\vert$ off) 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: two\+\_\+sided off
\end{DoxyParagraph}
\hypertarget{_compositor-_scripts_Applying-a-Compositor}{}\subsubsection{Applying a Compositor}\label{_compositor-_scripts_Applying-a-Compositor}
Adding a compositor instance to a viewport is very simple. All you need to do is\+:


\begin{DoxyCode}
\hyperlink{class_ogre_1_1_compositor_manager_a3c401a0186d115243eaef438450a0b17}{Ogre::CompositorManager::getSingleton}().
      \hyperlink{class_ogre_1_1_compositor_manager_a9b78bd2d9d32891d89aeea15c6d0b3ad}{addCompositor}(viewport, compositorName);
\end{DoxyCode}


Where viewport is a pointer to your viewport, and compositor\+Name is the name of the compositor to create an instance of. By doing this, a new instance of a compositor will be added to a new compositor chain on that viewport. You can call the method multiple times to add further compositors to the chain on this viewport. By default, each compositor which is added is disabled, but you can change this state by calling\+:


\begin{DoxyCode}
\hyperlink{class_ogre_1_1_compositor_manager_a3c401a0186d115243eaef438450a0b17}{Ogre::CompositorManager::getSingleton}().
      \hyperlink{class_ogre_1_1_compositor_manager_a40c9604cabf06d767110f4c2d73cf65d}{setCompositorEnabled}(viewport, compositorName, enabledOrDisabled);
\end{DoxyCode}


For more information on defining and using compositors, see Demo\+\_\+\+Compositor in the Samples area, together with the Examples.\+compositor script in the media area. \hypertarget{Particle-Scripts}{}\subsection{Particle Scripts}\label{Particle-Scripts}
Particle scripts allow you to define particle systems to be instantiated in your code without having to hard-\/code the settings themselves in your source code, allowing a very quick turnaround on any changes you make. Particle systems which are defined in scripts are used as templates, and multiple actual systems can be created from them at runtime.

Once scripts have been parsed, your code is free to instantiate systems based on them using the Scene\+Manager\+::create\+Particle\+System() method which can take both a name for the new system, and the name of the template to base it on (this template name is in the script).


\begin{DoxyCodeInclude}
\textcolor{comment}{// A sparkly purple fountain.}
particle\_system Examples/PurpleFountain
\{
    material        Examples/Flare2
    particle\_width  20
    particle\_height 40
    cull\_each       \textcolor{keyword}{false}
    quota           10000
    billboard\_type  oriented\_self
    
    \textcolor{comment}{// Area emitter.}
    emitter Point
    \{
        angle           15
        emission\_rate   75
        time\_to\_live    3
        direction       0 1 0
        velocity\_min    250
        velocity\_max    300
        colour\_range\_start  0 0 0
        colour\_range\_end    1 1 1
    \}

    \textcolor{comment}{// Gravity.}
    affector LinearForce
    \{
        force\_vector      0 -100 0
        force\_application add
    \}

    \textcolor{comment}{// Fader.}
    affector ColourFader
    \{
        red -0.25
        green -0.25
        blue -0.25
    \}
\}
\end{DoxyCodeInclude}
 A system can have top-\/level attributes set using the scripting commands available, such as ’quota’ to set the maximum number of particles allowed in the system. Emitters (which create particles) and affectors (which modify particles) are added as nested definitions within the script. The parameters available in the emitter and affector sections are entirely dependent on the type of emitter / affector.

For a detailed description of the core particle system attributes, see the list below\+:

\label{_Available-Particle-System-Attributes}%


\subsection*{Available Particle System Attributes}


\begin{DoxyItemize}
\item \href{#quota}{\tt quota}
\item \href{#particle_005fmaterial}{\tt material}
\item \href{#particle_005fwidth}{\tt particle\+\_\+width}
\item \href{#particle_005fheight}{\tt particle\+\_\+height}
\item \href{#cull_005feach}{\tt cull\+\_\+each}
\item \href{#billboard_005ftype}{\tt billboard\+\_\+type}
\item \href{#billboard_005forigin}{\tt billboard\+\_\+origin}
\item \href{#billboard_005frotation_005ftype}{\tt billboard\+\_\+rotation\+\_\+type}
\item \href{#common_005fdirection}{\tt common\+\_\+direction}
\item \href{#common_005fup_005fvector}{\tt common\+\_\+up\+\_\+vector}
\item \href{#particle_005frenderer}{\tt renderer}
\item \href{#particle_005fsorted}{\tt sorted}
\item \href{#particle_005flocalspace}{\tt local\+\_\+space}
\item \href{#particle_005fpoint_005frendering}{\tt point\+\_\+rendering}
\item \href{#particle_005faccurate_005ffacing}{\tt accurate\+\_\+facing}
\item \href{#iteration_005finterval}{\tt iteration\+\_\+interval}
\item \href{#nonvisible_005fupdate_005ftimeout}{\tt nonvisible\+\_\+update\+\_\+timeout}
\end{DoxyItemize}

See also\+: \href{#Particle-Emitters}{\tt Particle Emitters}, \href{#Particle-Affectors}{\tt Particle Affectors}

\label{_Particle-System-Attributes}%
 \label{_Particle-System-Attributes-1}%


\subsection*{Particle System Attributes}

This section describes to attributes which you can set on every particle system using scripts. All attributes have default values so all settings are optional in your script.

\label{_quota}%
\label{_quota-1}%


\subsection*{quota}

Sets the maximum number of particles this system is allowed to contain at one time. When this limit is exhausted, the emitters will not be allowed to emit any more particles until some destroyed (e.\+g. through their time\+\_\+to\+\_\+live running out). Note that you will almost always want to change this, since it defaults to a very low value (particle pools are only ever increased in size, never decreased).

format\+: quota $<$max\+\_\+particles$>$~\newline
 example\+: quota 10000~\newline
 default\+: 10~\newline


\label{_particle_005fmaterial}%
\label{_material-2}%


\subsection*{material}

Sets the name of the material which all particles in this system will use. All particles in a system use the same material, although each particle can tint this material through the use of it’s colour property.

format\+: material $<$material\+\_\+name$>$~\newline
 example\+: material Examples/\+Flare~\newline
 default\+: none (blank material)~\newline


\label{_particle_005fwidth}%
\label{_particle_005fwidth-1}%


\subsection*{particle\+\_\+width}

Sets the width of particles in world coordinates. Note that this property is absolute when billboard\+\_\+type (see below) is set to ’point’ or ’perpendicular\+\_\+self’, but is scaled by the length of the direction vector when billboard\+\_\+type is ’oriented\+\_\+common’, ’oriented\+\_\+self’ or ’perpendicular\+\_\+common’.~\newline


format\+: particle\+\_\+width $<$width$>$~\newline
 example\+: particle\+\_\+width 20~\newline
 default\+: 100~\newline


\label{_particle_005fheight}%
\label{_particle_005fheight-1}%


\subsection*{particle\+\_\+height}

Sets the height of particles in world coordinates. Note that this property is absolute when billboard\+\_\+type (see below) is set to ’point’ or ’perpendicular\+\_\+self’, but is scaled by the length of the direction vector when billboard\+\_\+type is ’oriented\+\_\+common’, ’oriented\+\_\+self’ or ’perpendicular\+\_\+common’.~\newline


format\+: particle\+\_\+height $<$height$>$~\newline
 example\+: particle\+\_\+height 20~\newline
 default\+: 100~\newline


\label{_cull_005feach}%
\label{_cull_005feach-1}%


\subsection*{cull\+\_\+each}

All particle systems are culled by the bounding box which contains all the particles in the system. This is normally sufficient for fairly locally constrained particle systems where most particles are either visible or not visible together. However, for those that spread particles over a wider area (e.\+g. a rain system), you may want to actually cull each particle individually to save on time, since it is far more likely that only a subset of the particles will be visible. You do this by setting the cull\+\_\+each parameter to true.

format\+: cull\+\_\+each $<$true$\vert$false$>$~\newline
 example\+: cull\+\_\+each true~\newline
 default\+: false~\newline


\label{_particle_005frenderer}%
\label{_renderer}%


\subsection*{renderer}

Particle systems do not render themselves, they do it through Particle\+Renderer classes. Those classes are registered with a manager in order to provide particle systems with a particular ’look’. O\+G\+RE comes configured with a default billboard-\/based renderer, but more can be added through plugins. Particle renders are registered with a unique name, and you can use that name in this attribute to determine the renderer to use. The default is ’billboard’.

Particle renderers can have attributes, which can be passed by setting them on the root particle system.

format\+: renderer $<$renderer\+\_\+name$>$~\newline
 default\+: billboard~\newline


\label{_particle_005fsorted}%
\label{_sorted}%


\subsection*{sorted}

By default, particles are not sorted. By setting this attribute to ’true’, the particles will be sorted with respect to the camera, furthest first. This can make certain rendering effects look better at a small sorting expense.

format\+: sorted $<$true$\vert$false$>$~\newline
 default\+: false~\newline


\label{_particle_005flocalspace}%
\label{_local_005fspace}%


\subsection*{local\+\_\+space}

By default, particles are emitted into world space, such that if you transform the node to which the system is attached, it will not affect the particles (only the emitters). This tends to give the normal expected behaviour, which is to model how real world particles travel independently from the objects they are emitted from. However, to create some effects you may want the particles to remain attached to the local space the emitter is in and to follow them directly. This option allows you to do that.

format\+: local\+\_\+space $<$true$\vert$false$>$~\newline
 default\+: false~\newline


\label{_billboard_005ftype}%
\label{_billboard_005ftype-1}%


\subsection*{billboard\+\_\+type}

This is actually an attribute of the ’billboard’ particle renderer (the default), and is an example of passing attributes to a particle renderer by declaring them directly within the system declaration. Particles using the default renderer are rendered using billboards, which are rectangles formed by 2 triangles which rotate to face the given direction. However, there is more than 1 way to orient a billboard. The classic approach is for the billboard to directly face the camera\+: this is the default behaviour. However this arrangement only looks good for particles which are representing something vaguely spherical like a light flare. For more linear effects like laser fire, you actually want the particle to have an orientation of it’s own.

format\+: billboard\+\_\+type $<$point$\vert$oriented\+\_\+common$\vert$oriented\+\_\+self$\vert$perpendicular\+\_\+common$\vert$perpendicular\+\_\+self$>$~\newline
 example\+: billboard\+\_\+type oriented\+\_\+self~\newline
 default\+: point~\newline


The options for this parameter are\+:


\begin{DoxyDescription}
\item[point ]

The default arrangement, this approximates spherical particles and the billboards always fully face the camera.


\item[oriented\+\_\+common ]

Particles are oriented around a common, typically fixed direction vector (see \href{#common_005fdirection}{\tt common\+\_\+direction}), which acts as their local Y axis. The billboard rotates only around this axis, giving the particle some sense of direction. Good for rainstorms, starfields etc where the particles will traveling in one direction -\/ this is slightly faster than oriented\+\_\+self (see below).


\item[oriented\+\_\+self ]

Particles are oriented around their own direction vector, which acts as their local Y axis. As the particle changes direction, so the billboard reorients itself to face this way. Good for laser fire, fireworks and other ’streaky’ particles that should look like they are traveling in their own direction.


\item[perpendicular\+\_\+common ]

Particles are perpendicular to a common, typically fixed direction vector (see \href{#common_005fdirection}{\tt common\+\_\+direction}), which acts as their local Z axis, and their local Y axis coplanar with common direction and the common up vector (see \href{#common_005fup_005fvector}{\tt common\+\_\+up\+\_\+vector}). The billboard never rotates to face the camera, you might use double-\/side material to ensure particles never culled by back-\/facing. Good for aureolas, rings etc where the particles will perpendicular to the ground -\/ this is slightly faster than perpendicular\+\_\+self (see below).


\item[perpendicular\+\_\+self ]

Particles are perpendicular to their own direction vector, which acts as their local Z axis, and their local Y axis coplanar with their own direction vector and the common up vector (see \href{#common_005fup_005fvector}{\tt common\+\_\+up\+\_\+vector}). The billboard never rotates to face the camera, you might use double-\/side material to ensure particles never culled by back-\/facing. Good for rings stack etc where the particles will perpendicular to their traveling direction.


\end{DoxyDescription}\label{_billboard_005forigin}%
\label{_billboard_005forigin-1}%


\subsection*{billboard\+\_\+origin}

Specifying the point which acts as the origin point for all billboard particles, controls the fine tuning of where a billboard particle appears in relation to it’s position.

format\+: billboard\+\_\+origin $<$top\+\_\+left$\vert$top\+\_\+center$\vert$top\+\_\+right$\vert$center\+\_\+left$\vert$center$\vert$center\+\_\+right$\vert$bottom\+\_\+left$\vert$bottom\+\_\+center$\vert$bottom\+\_\+right$>$~\newline
 example\+: billboard\+\_\+origin top\+\_\+right~\newline
 default\+: center~\newline


The options for this parameter are\+:


\begin{DoxyDescription}
\item[top\+\_\+left ]

The billboard origin is the top-\/left corner.


\item[top\+\_\+center ]

The billboard origin is the center of top edge.


\item[top\+\_\+right ]

The billboard origin is the top-\/right corner.


\item[center\+\_\+left ]

The billboard origin is the center of left edge.


\item[center ]

The billboard origin is the center.


\item[center\+\_\+right ]

The billboard origin is the center of right edge.


\item[bottom\+\_\+left ]

The billboard origin is the bottom-\/left corner.


\item[bottom\+\_\+center ]

The billboard origin is the center of bottom edge.


\item[bottom\+\_\+right ]

The billboard origin is the bottom-\/right corner.


\end{DoxyDescription}\label{_billboard_005frotation_005ftype}%
\label{_billboard_005frotation_005ftype-1}%


\subsection*{billboard\+\_\+rotation\+\_\+type}

By default, billboard particles will rotate the texture coordinates to according with particle rotation. But rotate texture coordinates has some disadvantage, e.\+g. the corners of the texture will lost after rotate, and the corners of the billboard will fill with unwanted texture area when using wrap address mode or sub-\/texture sampling. This settings allow you specifying other rotation type.

format\+: billboard\+\_\+rotation\+\_\+type $<$vertex$\vert$texcoord$>$~\newline
 example\+: billboard\+\_\+rotation\+\_\+type vertex~\newline
 default\+: texcoord~\newline


The options for this parameter are\+:


\begin{DoxyDescription}
\item[vertex ]

Billboard particles will rotate the vertices around their facing direction to according with particle rotation. Rotate vertices guarantee texture corners exactly match billboard corners, thus has advantage mentioned above, but should take more time to generate the vertices.


\item[texcoord ]

Billboard particles will rotate the texture coordinates to according with particle rotation. Rotate texture coordinates is faster than rotate vertices, but has some disadvantage mentioned above.


\end{DoxyDescription}\label{_common_005fdirection}%
\label{_common_005fdirection-1}%


\subsection*{common\+\_\+direction}

Only required if \href{#billboard_005ftype}{\tt billboard\+\_\+type} is set to oriented\+\_\+common or perpendicular\+\_\+common, this vector is the common direction vector used to orient all particles in the system.

format\+: common\+\_\+direction $<$x$>$ $<$y$>$ $<$z$>$~\newline
 example\+: common\+\_\+direction 0 -\/1 0~\newline
 default\+: 0 0 1~\newline
 See also\+: \href{#Particle-Emitters}{\tt Particle Emitters}, \href{#Particle-Affectors}{\tt Particle Affectors}

\label{_common_005fup_005fvector}%
\label{_common_005fup_005fvector-1}%


\subsection*{common\+\_\+up\+\_\+vector}

Only required if \href{#billboard_005ftype}{\tt billboard\+\_\+type} is set to perpendicular\+\_\+self or perpendicular\+\_\+common, this vector is the common up vector used to orient all particles in the system.

format\+: common\+\_\+up\+\_\+vector $<$x$>$ $<$y$>$ $<$z$>$~\newline
 example\+: common\+\_\+up\+\_\+vector 0 1 0~\newline
 default\+: 0 1 0~\newline
 See also\+: \href{#Particle-Emitters}{\tt Particle Emitters}, \href{#Particle-Affectors}{\tt Particle Affectors}

\label{_particle_005fpoint_005frendering}%
\label{_point_005frendering}%


\subsection*{point\+\_\+rendering}

This is actually an attribute of the ’billboard’ particle renderer (the default), and sets whether or not the Billboard\+Set will use point rendering rather than manually generated quads.

By default a Billboard\+Set is rendered by generating geometry for a textured quad in memory, taking into account the size and orientation settings, and uploading it to the video card. The alternative is to use hardware point rendering, which means that only one position needs to be sent per billboard rather than 4 and the hardware sorts out how this is rendered based on the render state.

Using point rendering is faster than generating quads manually, but is more restrictive. The following restrictions apply\+:


\begin{DoxyItemize}
\item Only the ’point’ orientation type is supported
\item Size and appearance of each particle is controlled by the material pass (\href{#point_005fsize}{\tt point\+\_\+size}, \href{#point_005fsize_005fattenuation}{\tt point\+\_\+size\+\_\+attenuation}, \href{#point_005fsprites}{\tt point\+\_\+sprites})
\item Per-\/particle size is not supported (stems from the above)
\item Per-\/particle rotation is not supported, and this can only be controlled through texture unit rotation in the material definition
\item Only ’center’ origin is supported
\item Some drivers have an upper limit on the size of points they support -\/ this can even vary between A\+P\+Is on the same card! Don’t rely on point sizes that cause the point sprites to get very large on screen, since they may get clamped on some cards. Upper sizes can range from 64 to 256 pixels.
\end{DoxyItemize}

You will almost certainly want to enable in your material pass both point attenuation and point sprites if you use this option.

\label{_particle_005faccurate_005ffacing}%
\label{_accurate_005ffacing}%


\subsection*{accurate\+\_\+facing}

This is actually an attribute of the ’billboard’ particle renderer (the default), and sets whether or not the Billboard\+Set will use a slower but more accurate calculation for facing the billboard to the camera. Bt default it uses the camera direction, which is faster but means the billboards don’t stay in the same orientation as you rotate the camera. The ’accurate\+\_\+facing true’ option makes the calculation based on a vector from each billboard to the camera, which means the orientation is constant even whilst the camera rotates.

format\+: accurate\+\_\+facing on$\vert$off~\newline
 default\+: accurate\+\_\+facing off 0~\newline


\label{_iteration_005finterval}%
\label{_iteration_005finterval-1}%


\subsection*{iteration\+\_\+interval}

Usually particle systems are updated based on the frame rate; however this can give variable results with more extreme frame rate ranges, particularly at lower frame rates. You can use this option to make the update frequency a fixed interval, whereby at lower frame rates, the particle update will be repeated at the fixed interval until the frame time is used up. A value of 0 means the default frame time iteration.

format\+: iteration\+\_\+interval $<$secs$>$~\newline
 example\+: iteration\+\_\+interval 0.\+01~\newline
 default\+: iteration\+\_\+interval 0~\newline


\label{_nonvisible_005fupdate_005ftimeout}%
\label{_nonvisible_005fupdate_005ftimeout-1}%


\subsection*{nonvisible\+\_\+update\+\_\+timeout}

Sets when the particle system should stop updating after it hasn’t been visible for a while. By default, visible particle systems update all the time, even when not in view. This means that they are guaranteed to be consistent when they do enter view. However, this comes at a cost, updating particle systems can be expensive, especially if they are perpetual. This option lets you set a ’timeout’ on the particle system, so that if it isn’t visible for this amount of time, it will stop updating until it is next visible. A value of 0 disables the timeout and always updates.

format\+: nonvisible\+\_\+update\+\_\+timeout $<$secs$>$~\newline
 example\+: nonvisible\+\_\+update\+\_\+timeout 10~\newline
 default\+: nonvisible\+\_\+update\+\_\+timeout 0~\newline
\hypertarget{_particle-_scripts_Particle-Emitters}{}\subsubsection{Particle Emitters}\label{_particle-_scripts_Particle-Emitters}
Particle emitters are classified by ’type’ e.\+g. ’\+Point’ emitters emit from a single point whilst ’\+Box’ emitters emit randomly from an area. New emitters can be added to \hyperlink{namespace_ogre}{Ogre} by creating plugins. You add an emitter to a system by nesting another section within it, headed with the keyword ’emitter’ followed by the name of the type of emitter (case sensitive). \hyperlink{namespace_ogre}{Ogre} currently supports ’\+Point’, ’\+Box’, ’\+Cylinder’, ’\+Ellipsoid’, ’\+Hollow\+Ellipsoid’ and ’\+Ring’ emitters.

It is also possible to ’emit emitters’ -\/ that is, have new emitters spawned based on the position of particles. See \href{#Emitting-Emitters}{\tt Emitting Emitters}

\label{_Particle-Emitter-Universal-Attributes}%


\subsection*{Particle Emitter Universal Attributes}


\begin{DoxyItemize}
\item \href{#angle}{\tt angle}
\item \href{#colour}{\tt colour}
\item \href{#colour_005frange_005fstart}{\tt colour\+\_\+range\+\_\+start}
\item \href{#colour_005frange_005fend}{\tt colour\+\_\+range\+\_\+end}
\item \href{#direction}{\tt direction}
\item \href{#direction_005fposition_005freference}{\tt direction\+\_\+position\+\_\+reference}
\item \href{#emission_005frate}{\tt emission\+\_\+rate}
\item \href{#position}{\tt position}
\item \href{#velocity}{\tt velocity}
\item \href{#velocity_005fmin}{\tt velocity\+\_\+min}
\item \href{#velocity_005fmax}{\tt velocity\+\_\+max}
\item \href{#time_005fto_005flive}{\tt time\+\_\+to\+\_\+live}
\item \href{#time_005fto_005flive_005fmin}{\tt time\+\_\+to\+\_\+live\+\_\+min}
\item \href{#time_005fto_005flive_005fmax}{\tt time\+\_\+to\+\_\+live\+\_\+max}
\item \href{#duration}{\tt duration}
\item \href{#duration_005fmin}{\tt duration\+\_\+min}
\item \href{#duration_005fmax}{\tt duration\+\_\+max}
\item \href{#repeat_005fdelay}{\tt repeat\+\_\+delay}
\item \href{#repeat_005fdelay_005fmin}{\tt repeat\+\_\+delay\+\_\+min}
\item \href{#repeat_005fdelay_005fmax}{\tt repeat\+\_\+delay\+\_\+max}
\end{DoxyItemize}

See also\+: \href{#Particle-Scripts}{\tt Particle Scripts}, \href{#Particle-Affectors}{\tt Particle Affectors}

\label{_Particle-Emitter-Attributes}%
 \label{_Particle-Emitter-Attributes-1}%


\subsection*{Particle Emitter Attributes}

This section describes the common attributes of all particle emitters. Specific emitter types may also support their own extra attributes.

\label{_angle}%
\label{_angle-1}%


\subsection*{angle}

Sets the maximum angle (in degrees) which emitted particles may deviate from the direction of the emitter (see direction). Setting this to 10 allows particles to deviate up to 10 degrees in any direction away from the emitter’s direction. A value of 180 means emit in any direction, whilst 0 means emit always exactly in the direction of the emitter.

format\+: angle $<$degrees$>$~\newline
 example\+: angle 30~\newline
 default\+: 0~\newline


\label{_colour}%
\label{_colour-1}%


\subsection*{colour}

Sets a static colour for all particle emitted. Also see the colour\+\_\+range\+\_\+start and colour\+\_\+range\+\_\+end attributes for setting a range of colours. The format of the colour parameter is \char`\"{}r g b a\char`\"{}, where each component is a value from 0 to 1, and the alpha value is optional (assumes 1 if not specified).

format\+: colour $<$r$>$ $<$g$>$ $<$b$>$ \mbox{[}$<$a$>$\mbox{]}~\newline
 example\+: colour 1 0 0 1~\newline
 default\+: 1 1 1 1~\newline


\label{_colour_005frange_005fstart}%
\label{_colour_005frange_005fend}%


\subsection*{colour\+\_\+range\+\_\+start \& colour\+\_\+range\+\_\+end}

As the ’colour’ attribute, except these 2 attributes must be specified together, and indicate the range of colours available to emitted particles. The actual colour will be randomly chosen between these 2 values.

format\+: as colour~\newline
 example (generates random colours between red and blue)\+:~\newline
     colour\+\_\+range\+\_\+start 1 0 0~\newline
     colour\+\_\+range\+\_\+end 0 0 1~\newline
 default\+: both 1 1 1 1~\newline


\label{_direction}%
\label{_direction-1}%


\subsection*{direction}

Sets the direction of the emitter. This is relative to the Scene\+Node which the particle system is attached to, meaning that as with other movable objects changing the orientation of the node will also move the emitter.

format\+: direction $<$x$>$ $<$y$>$ $<$z$>$~\newline
 example\+: direction 0 1 0~\newline
 default\+: 1 0 0~\newline


\label{_direction_005fposition_005freference}%
\label{_direction_005fposition_005freference-1}%


\subsection*{direction\+\_\+position\+\_\+reference}

Sets the position reference of the emitter. This supersedes direction when present. The last parameter must be 1 to enable it, 0 to disable. You may still want to set the direction to setup orientation of the emitter’s dimensions. When present, particles direction is calculated at the time of emission by doing (particle\+Position -\/ reference\+Position); therefore particles will travel in a particular direction or in every direction depending on where the particles are originated, and the location of the reference position. Note angle still works to apply some randomness after the direction vector is generated. This parameter is specially useful to create explosions and implosions (when velocity is negative) best paired with Hollow\+Ellipsoid and Ring emitters. This is relative to the Scene\+Node which the particle system is attached to, meaning that as with other movable objects changing the orientation of the node will also move the emitter.

format\+: direction\+\_\+position\+\_\+reference $<$x$>$ $<$y$>$ $<$z$>$ $<$enable$>$~\newline
 example\+: direction\+\_\+position\+\_\+reference 0 -\/10 0 1~\newline
 default\+: direction\+\_\+position\+\_\+reference 0 0 0 0~\newline


\label{_emission_005frate}%
\label{_emission_005frate-1}%


\subsection*{emission\+\_\+rate}

Sets how many particles per second should be emitted. The specific emitter does not have to emit these in a continuous burst -\/ this is a relative parameter and the emitter may choose to emit all of the second’s worth of particles every half-\/second for example, the behaviour depends on the emitter. The emission rate will also be limited by the particle system’s ’quota’ setting.

format\+: emission\+\_\+rate $<$particles\+\_\+per\+\_\+second$>$~\newline
 example\+: emission\+\_\+rate 50~\newline
 default\+: 10~\newline


\label{_position}%
\label{_position-1}%


\subsection*{position}

Sets the position of the emitter relative to the Scene\+Node the particle system is attached to.

format\+: position $<$x$>$ $<$y$>$ $<$z$>$~\newline
 example\+: position 10 0 40~\newline
 default\+: 0 0 0~\newline


\label{_velocity}%
\label{_velocity-1}%


\subsection*{velocity}

Sets a constant velocity for all particles at emission time. See also the velocity\+\_\+min and velocity\+\_\+max attributes which allow you to set a range of velocities instead of a fixed one.

format\+: velocity $<$world\+\_\+units\+\_\+per\+\_\+second$>$~\newline
 example\+: velocity 100~\newline
 default\+: 1~\newline


\label{_velocity_005fmin}%
\label{_velocity_005fmax}%


\subsection*{velocity\+\_\+min \& velocity\+\_\+max}

As ’velocity’ except these attributes set a velocity range and each particle is emitted with a random velocity within this range.

format\+: as velocity~\newline
 example\+:~\newline
     velocity\+\_\+min 50~\newline
     velocity\+\_\+max 100~\newline
 default\+: both 1~\newline


\label{_time_005fto_005flive}%
\label{_time_005fto_005flive-1}%


\subsection*{time\+\_\+to\+\_\+live}

Sets the number of seconds each particle will ’live’ for before being destroyed. NB it is possible for particle affectors to alter this in flight, but this is the value given to particles on emission. See also the time\+\_\+to\+\_\+live\+\_\+min and time\+\_\+to\+\_\+live\+\_\+max attributes which let you set a lifetime range instead of a fixed one.

format\+: time\+\_\+to\+\_\+live $<$seconds$>$~\newline
 example\+: time\+\_\+to\+\_\+live 10~\newline
 default\+: 5~\newline


\label{_time_005fto_005flive_005fmin}%
\label{_time_005fto_005flive_005fmax}%


\subsection*{time\+\_\+to\+\_\+live\+\_\+min \& time\+\_\+to\+\_\+live\+\_\+max}

As time\+\_\+to\+\_\+live, except this sets a range of lifetimes and each particle gets a random value in-\/between on emission.

format\+: as time\+\_\+to\+\_\+live~\newline
 example\+:~\newline
     time\+\_\+to\+\_\+live\+\_\+min 2~\newline
     time\+\_\+to\+\_\+live\+\_\+max 5~\newline
 default\+: both 5~\newline
 ~\newline


\label{_duration}%
\label{_duration-1}%


\subsection*{duration}

Sets the number of seconds the emitter is active. The emitter can be started again, see \href{#repeat_005fdelay}{\tt repeat\+\_\+delay}. A value of 0 means infinite duration. See also the duration\+\_\+min and duration\+\_\+max attributes which let you set a duration range instead of a fixed one.

format\+: duration $<$seconds$>$~\newline
 example\+:~\newline
     duration 2.\+5~\newline
 default\+: 0~\newline
 ~\newline


\label{_duration_005fmin}%
\label{_duration_005fmax}%


\subsection*{duration\+\_\+min \& duration\+\_\+max}

As duration, except these attributes set a variable time range between the min and max values each time the emitter is started.

format\+: as duration~\newline
 example\+:~\newline
     duration\+\_\+min 2~\newline
     duration\+\_\+max 5~\newline
 default\+: both 0~\newline
 ~\newline


\label{_repeat_005fdelay}%
\label{_repeat_005fdelay-1}%


\subsection*{repeat\+\_\+delay}

Sets the number of seconds to wait before the emission is repeated when stopped by a limited \href{#duration}{\tt duration}. See also the repeat\+\_\+delay\+\_\+min and repeat\+\_\+delay\+\_\+max attributes which allow you to set a range of repeat\+\_\+delays instead of a fixed one.

format\+: repeat\+\_\+delay $<$seconds$>$~\newline
 example\+:~\newline
     repeat\+\_\+delay 2.\+5~\newline
 default\+: 0~\newline
 ~\newline


\label{_repeat_005fdelay_005fmin}%
\label{_repeat_005fdelay_005fmax}%


\subsection*{repeat\+\_\+delay\+\_\+min \& repeat\+\_\+delay\+\_\+max}

As repeat\+\_\+delay, except this sets a range of repeat delays and each time the emitter is started it gets a random value in-\/between.

format\+: as repeat\+\_\+delay~\newline
 example\+:~\newline
     repeat\+\_\+delay 2~\newline
     repeat\+\_\+delay 5~\newline
 default\+: both 0~\newline
 ~\newline


See also\+: \href{#Standard-Particle-Emitters}{\tt Standard Particle Emitters}, \href{#Particle-Scripts}{\tt Particle Scripts}, \href{#Particle-Affectors}{\tt Particle Affectors}\hypertarget{_particle-_scripts_Standard-Particle-Emitters}{}\subsubsection{Standard Particle Emitters}\label{_particle-_scripts_Standard-Particle-Emitters}
\hyperlink{namespace_ogre}{Ogre} comes preconfigured with a few particle emitters. New ones can be added by creating plugins\+: see the Plugin\+\_\+\+Particle\+FX project as an example of how you would do this (this is where these emitters are implemented).


\begin{DoxyItemize}
\item \href{#Point-Emitter}{\tt Point Emitter}
\item \href{#Box-Emitter}{\tt Box Emitter}
\item \href{#Cylinder-Emitter}{\tt Cylinder Emitter}
\item \href{#Ellipsoid-Emitter}{\tt Ellipsoid Emitter}
\item \href{#Hollow-Ellipsoid-Emitter}{\tt Hollow Ellipsoid Emitter}
\item \href{#Ring-Emitter}{\tt Ring Emitter}
\end{DoxyItemize}\hypertarget{_particle-_scripts_Point-Emitter}{}\paragraph{Point Emitter}\label{_particle-_scripts_Point-Emitter}
This emitter emits particles from a single point, which is it’s position. This emitter has no additional attributes over an above the standard emitter attributes.

To create a point emitter, include a section like this within your particle system script\+:


\begin{DoxyCode}
emitter Point
\{
    \textcolor{comment}{// Settings go here}
\}
\end{DoxyCode}


~\newline


Please note that the name of the emitter (’\+Point’) is case-\/sensitive.\hypertarget{_particle-_scripts_Box-Emitter}{}\paragraph{Box Emitter}\label{_particle-_scripts_Box-Emitter}
This emitter emits particles from a random location within a 3-\/dimensional box. It’s extra attributes are\+:


\begin{DoxyDescription}
\item[width ]

Sets the width of the box (this is the size of the box along it’s local X axis, which is dependent on the ’direction’ attribute which forms the box’s local Z).~\newline
 format\+: width $<$units$>$~\newline
 example\+: width 250~\newline
 default\+: 100~\newline



\item[height ]

Sets the height of the box (this is the size of the box along it’s local Y axis, which is dependent on the ’direction’ attribute which forms the box’s local Z).~\newline
 format\+: height $<$units$>$~\newline
 example\+: height 250~\newline
 default\+: 100~\newline



\item[depth ]

Sets the depth of the box (this is the size of the box along it’s local Z axis, which is the same as the ’direction’ attribute).~\newline
 format\+: depth $<$units$>$~\newline
 example\+: depth 250~\newline
 default\+: 100~\newline



\end{DoxyDescription}~\newline


To create a box emitter, include a section like this within your particle system script\+:


\begin{DoxyCode}
emitter Box
\{
    \textcolor{comment}{// Settings go here}
\}
\end{DoxyCode}
\hypertarget{_particle-_scripts_Cylinder-Emitter}{}\paragraph{Cylinder Emitter}\label{_particle-_scripts_Cylinder-Emitter}
This emitter emits particles in a random direction from within a cylinder area, where the cylinder is oriented along the Z-\/axis. This emitter has exactly the same parameters as the \href{#Box-Emitter}{\tt Box Emitter} so there are no additional parameters to consider here -\/ the width and height determine the shape of the cylinder along it’s axis (if they are different it is an ellipsoid cylinder), the depth determines the length of the cylinder.\hypertarget{_particle-_scripts_Ellipsoid-Emitter}{}\paragraph{Ellipsoid Emitter}\label{_particle-_scripts_Ellipsoid-Emitter}
This emitter emits particles from within an ellipsoid shaped area, i.\+e. a sphere or squashed-\/sphere area. The parameters are again identical to the \href{#Box-Emitter}{\tt Box Emitter}, except that the dimensions describe the widest points along each of the axes.\hypertarget{_particle-_scripts_Hollow-Ellipsoid-Emitter}{}\paragraph{Hollow Ellipsoid Emitter}\label{_particle-_scripts_Hollow-Ellipsoid-Emitter}
This emitter is just like \href{#Ellipsoid-Emitter}{\tt Ellipsoid Emitter} except that there is a hollow area in the center of the ellipsoid from which no particles are emitted. Therefore it has 3 extra parameters in order to define this area\+:


\begin{DoxyDescription}
\item[inner\+\_\+width ]

The width of the inner area which does not emit any particles.


\item[inner\+\_\+height ]

The height of the inner area which does not emit any particles.


\item[inner\+\_\+depth ]

The depth of the inner area which does not emit any particles.


\end{DoxyDescription}\hypertarget{_particle-_scripts_Ring-Emitter}{}\paragraph{Ring Emitter}\label{_particle-_scripts_Ring-Emitter}
This emitter emits particles from a ring-\/shaped area, i.\+e. a little like \href{#Hollow-Ellipsoid-Emitter}{\tt Hollow Ellipsoid Emitter} except only in 2 dimensions.


\begin{DoxyDescription}
\item[inner\+\_\+width ]

The width of the inner area which does not emit any particles.


\item[inner\+\_\+height ]

The height of the inner area which does not emit any particles.


\end{DoxyDescription}

See also\+: \href{#Particle-Scripts}{\tt Particle Scripts}, \href{#Particle-Emitters}{\tt Particle Emitters}\hypertarget{_particle-_scripts_Emitting-Emitters}{}\paragraph{Emitting Emitters}\label{_particle-_scripts_Emitting-Emitters}
It is possible to spawn new emitters on the expiry of particles, for example to product ’firework’ style effects. This is controlled via the following directives\+:


\begin{DoxyDescription}
\item[emit\+\_\+emitter\+\_\+quota ]

This parameter is a system-\/level parameter telling the system how many emitted emitters may be in use at any one time. This is just to allow for the space allocation process.


\item[name ]

This parameter is an emitter-\/level parameter, giving a name to an emitter. This can then be referred to in another emitter as the new emitter type to spawn when an emitted particle dies.


\item[emit\+\_\+emitter ]

This is an emitter-\/level parameter, and if specified, it means that when particles emitted by this emitter die, they spawn a new emitter of the named type.


\end{DoxyDescription}\hypertarget{_particle-_scripts_Particle-Affectors}{}\subsubsection{Particle Affectors}\label{_particle-_scripts_Particle-Affectors}
Particle affectors modify particles over their lifetime. They are classified by ’type’ e.\+g. ’\+Linear\+Force’ affectors apply a force to all particles, whilst ’\+Colour\+Fader’ affectors alter the colour of particles in flight. New affectors can be added to \hyperlink{namespace_ogre}{Ogre} by creating plugins. You add an affector to a system by nesting another section within it, headed with the keyword ’affector’ followed by the name of the type of affector (case sensitive). \hyperlink{namespace_ogre}{Ogre} currently supports ’\+Linear\+Force’ and ’\+Colour\+Fader’ affectors.

Particle affectors actually have no universal attributes; they are all specific to the type of affector.

See also\+: \href{#Standard-Particle-Affectors}{\tt Standard Particle Affectors}, \href{#Particle-Scripts}{\tt Particle Scripts}, \href{#Particle-Emitters}{\tt Particle Emitters}\hypertarget{_particle-_scripts_Standard-Particle-Affectors}{}\subsubsection{Standard Particle Affectors}\label{_particle-_scripts_Standard-Particle-Affectors}
\hyperlink{namespace_ogre}{Ogre} comes preconfigured with a few particle affectors. New ones can be added by creating plugins\+: see the Plugin\+\_\+\+Particle\+FX project as an example of how you would do this (this is where these affectors are implemented).


\begin{DoxyItemize}
\item \href{#Linear-Force-Affector}{\tt Linear Force Affector}
\item \href{#ColourFader-Affector}{\tt Colour\+Fader Affector}
\item \href{#ColourFader2-Affector}{\tt Colour\+Fader2 Affector}
\item \href{#Scaler-Affector}{\tt Scaler Affector}
\item \href{#Rotator-Affector}{\tt Rotator Affector}
\item \href{#ColourInterpolator-Affector}{\tt Colour\+Interpolator Affector}
\item \href{#ColourImage-Affector}{\tt Colour\+Image Affector}
\item \href{#DeflectorPlane-Affector}{\tt Deflector\+Plane Affector}
\item \href{#DirectionRandomiser-Affector}{\tt Direction\+Randomiser Affector}
\end{DoxyItemize}\hypertarget{_particle-_scripts_Linear-Force-Affector}{}\paragraph{Linear Force Affector}\label{_particle-_scripts_Linear-Force-Affector}
This affector applies a force vector to all particles to modify their trajectory. Can be used for gravity, wind, or any other linear force. It’s extra attributes are\+:


\begin{DoxyDescription}
\item[force\+\_\+vector ]

Sets the vector for the force to be applied to every particle. The magnitude of this vector determines how strong the force is.~\newline
     format\+: force\+\_\+vector $<$x$>$ $<$y$>$ $<$z$>$~\newline
     example\+: force\+\_\+vector 50 0 -\/50~\newline
     default\+: 0 -\/100 0 (a fair gravity effect)~\newline



\item[force\+\_\+application ]

Sets the way in which the force vector is applied to particle momentum.~\newline
     format\+: force\+\_\+application $<$add$\vert$average$>$~\newline
     example\+: force\+\_\+application average~\newline
     default\+: add~\newline
 The options are\+:


\begin{DoxyDescription}
\item[average ]

The resulting momentum is the average of the force vector and the particle’s current motion. Is self-\/stabilising but the speed at which the particle changes direction is non-\/linear.


\item[add ]

The resulting momentum is the particle’s current motion plus the force vector. This is traditional force acceleration but can potentially result in unlimited velocity.


\end{DoxyDescription}
\end{DoxyDescription}~\newline


To create a linear force affector, include a section like this within your particle system script\+:


\begin{DoxyCode}
affector LinearForce
\{
    \textcolor{comment}{// Settings go here}
\}
\end{DoxyCode}


Please note that the name of the affector type (’\+Linear\+Force’) is case-\/sensitive.\hypertarget{_particle-_scripts_ColourFader-Affector}{}\paragraph{Colour\+Fader Affector}\label{_particle-_scripts_ColourFader-Affector}
This affector modifies the colour of particles in flight. It’s extra attributes are\+:


\begin{DoxyDescription}
\item[red ]

Sets the adjustment to be made to the red component of the particle colour per second.~\newline
     format\+: red $<$delta\+\_\+value$>$~\newline
     example\+: red -\/0.\+1~\newline
     default\+: 0~\newline



\item[green ]

Sets the adjustment to be made to the green component of the particle colour per second.~\newline
     format\+: green $<$delta\+\_\+value$>$~\newline
     example\+: green -\/0.\+1~\newline
     default\+: 0~\newline



\item[blue ]

Sets the adjustment to be made to the blue component of the particle colour per second.~\newline
     format\+: blue $<$delta\+\_\+value$>$~\newline
     example\+: blue -\/0.\+1~\newline
     default\+: 0~\newline



\item[alpha ]

Sets the adjustment to be made to the alpha component of the particle colour per second.~\newline
     format\+: alpha $<$delta\+\_\+value$>$~\newline
 example\+: alpha -\/0.\+1~\newline
 default\+: 0~\newline



\end{DoxyDescription}

To create a colour fader affector, include a section like this within your particle system script\+:


\begin{DoxyCode}
affector ColourFader
\{
    \textcolor{comment}{// Settings go here}
\}
\end{DoxyCode}
\hypertarget{_particle-_scripts_ColourFader2-Affector}{}\paragraph{Colour\+Fader2 Affector}\label{_particle-_scripts_ColourFader2-Affector}
This affector is similar to the \href{#ColourFader-Affector}{\tt Colour\+Fader Affector}, except it introduces two states of colour changes as opposed to just one. The second colour change state is activated once a specified amount of time remains in the particles life.


\begin{DoxyDescription}
\item[red1 ]

Sets the adjustment to be made to the red component of the particle colour per second for the first state.~\newline
     format\+: red $<$delta\+\_\+value$>$~\newline
     example\+: red -\/0.\+1~\newline
     default\+: 0~\newline



\item[green1 ]

Sets the adjustment to be made to the green component of the particle colour per second for the first state.~\newline
     format\+: green $<$delta\+\_\+value$>$~\newline
     example\+: green -\/0.\+1~\newline
     default\+: 0~\newline



\item[blue1 ]

Sets the adjustment to be made to the blue component of the particle colour per second for the first state.~\newline
     format\+: blue $<$delta\+\_\+value$>$~\newline
     example\+: blue -\/0.\+1~\newline
     default\+: 0~\newline



\item[alpha1 ]

Sets the adjustment to be made to the alpha component of the particle colour per second for the first state.~\newline
     format\+: alpha $<$delta\+\_\+value$>$~\newline
 example\+: alpha -\/0.\+1~\newline
 default\+: 0~\newline



\item[red2 ]

Sets the adjustment to be made to the red component of the particle colour per second for the second state.~\newline
     format\+: red $<$delta\+\_\+value$>$~\newline
     example\+: red -\/0.\+1~\newline
     default\+: 0~\newline



\item[green2 ]

Sets the adjustment to be made to the green component of the particle colour per second for the second state.~\newline
     format\+: green $<$delta\+\_\+value$>$~\newline
     example\+: green -\/0.\+1~\newline
     default\+: 0~\newline



\item[blue2 ]

Sets the adjustment to be made to the blue component of the particle colour per second for the second state.~\newline
     format\+: blue $<$delta\+\_\+value$>$~\newline
     example\+: blue -\/0.\+1~\newline
     default\+: 0~\newline



\item[alpha2 ]

Sets the adjustment to be made to the alpha component of the particle colour per second for the second state.~\newline
     format\+: alpha $<$delta\+\_\+value$>$~\newline
 example\+: alpha -\/0.\+1~\newline
 default\+: 0~\newline



\item[state\+\_\+change ]

When a particle has this much time left to live, it will switch to state 2.~\newline
     format\+: state\+\_\+change $<$seconds$>$~\newline
 example\+: state\+\_\+change 2~\newline
 default\+: 1~\newline



\end{DoxyDescription}

To create a Colour\+Fader2 affector, include a section like this within your particle system script\+:


\begin{DoxyCode}
affector ColourFader2
\{
    \textcolor{comment}{// Settings go here}
\}
\end{DoxyCode}
\hypertarget{_particle-_scripts_Scaler-Affector}{}\paragraph{Scaler Affector}\label{_particle-_scripts_Scaler-Affector}
This affector scales particles in flight. It’s extra attributes are\+:


\begin{DoxyDescription}
\item[rate ]

The amount by which to scale the particles in both the x and y direction per second.


\end{DoxyDescription}

To create a scale affector, include a section like this within your particle system script\+:


\begin{DoxyCode}
affector Scaler
\{
    \textcolor{comment}{// Settings go here}
\}
\end{DoxyCode}
\hypertarget{_particle-_scripts_Rotator-Affector}{}\paragraph{Rotator Affector}\label{_particle-_scripts_Rotator-Affector}
This affector rotates particles in flight. This is done by rotating the texture. It’s extra attributes are\+:


\begin{DoxyDescription}
\item[rotation\+\_\+speed\+\_\+range\+\_\+start ]

The start of a range of rotation speeds to be assigned to emitted particles.~\newline
     format\+: rotation\+\_\+speed\+\_\+range\+\_\+start $<$degrees\+\_\+per\+\_\+second$>$~\newline
 example\+: rotation\+\_\+speed\+\_\+range\+\_\+start 90~\newline
 default\+: 0~\newline



\item[rotation\+\_\+speed\+\_\+range\+\_\+end ]

The end of a range of rotation speeds to be assigned to emitted particles.~\newline
     format\+: rotation\+\_\+speed\+\_\+range\+\_\+end $<$degrees\+\_\+per\+\_\+second$>$~\newline
 example\+: rotation\+\_\+speed\+\_\+range\+\_\+end 180~\newline
 default\+: 0~\newline



\item[rotation\+\_\+range\+\_\+start ]

The start of a range of rotation angles to be assigned to emitted particles.~\newline
     format\+: rotation\+\_\+range\+\_\+start $<$degrees$>$~\newline
 example\+: rotation\+\_\+range\+\_\+start 0~\newline
 default\+: 0~\newline



\item[rotation\+\_\+range\+\_\+end ]

The end of a range of rotation angles to be assigned to emitted particles.~\newline
     format\+: rotation\+\_\+range\+\_\+end $<$degrees$>$~\newline
 example\+: rotation\+\_\+range\+\_\+end 360~\newline
 default\+: 0~\newline



\end{DoxyDescription}

To create a rotate affector, include a section like this within your particle system script\+:


\begin{DoxyCode}
affector Rotator
\{
    \textcolor{comment}{// Settings go here}
\}
\end{DoxyCode}
\hypertarget{_particle-_scripts_ColourInterpolator-Affector}{}\paragraph{Colour\+Interpolator Affector}\label{_particle-_scripts_ColourInterpolator-Affector}
Similar to the Colour\+Fader and Colour\+Fader2 Affectors, this affector modifies the colour of particles in flight, except it has a variable number of defined stages. It swaps the particle colour for several stages in the life of a particle and interpolates between them. It’s extra attributes are\+:


\begin{DoxyDescription}
\item[time0 ]

The point in time of stage 0.~\newline
     format\+: time0 $<$0-\/1 based on lifetime$>$~\newline
 example\+: time0 0~\newline
 default\+: 1~\newline



\item[colour0 ]

The colour at stage 0.~\newline
     format\+: colour0 $<$r$>$ $<$g$>$ $<$b$>$ \mbox{[}$<$a$>$\mbox{]}~\newline
 example\+: colour0 1 0 0 1~\newline
 default\+: 0.\+5 0.\+5 0.\+5 0.\+0~\newline



\item[time1 ]

The point in time of stage 1.~\newline
     format\+: time1 $<$0-\/1 based on lifetime$>$~\newline
 example\+: time1 0.\+5~\newline
 default\+: 1~\newline



\item[colour1 ]

The colour at stage 1.~\newline
     format\+: colour1 $<$r$>$ $<$g$>$ $<$b$>$ \mbox{[}$<$a$>$\mbox{]}~\newline
 example\+: colour1 0 1 0 1~\newline
 default\+: 0.\+5 0.\+5 0.\+5 0.\+0~\newline



\item[time2 ]

The point in time of stage 2.~\newline
     format\+: time2 $<$0-\/1 based on lifetime$>$~\newline
 example\+: time2 1~\newline
 default\+: 1~\newline



\item[colour2 ]

The colour at stage 2.~\newline
     format\+: colour2 $<$r$>$ $<$g$>$ $<$b$>$ \mbox{[}$<$a$>$\mbox{]}~\newline
 example\+: colour2 0 0 1 1~\newline
 default\+: 0.\+5 0.\+5 0.\+5 0.\+0~\newline



\item[\mbox{[}...\mbox{]} ]
\end{DoxyDescription}

The number of stages is variable. The maximal number of stages is 6; where time5 and colour5 are the last possible parameters. To create a colour interpolation affector, include a section like this within your particle system script\+:


\begin{DoxyCode}
affector ColourInterpolator
\{
    \textcolor{comment}{// Settings go here}
\}
\end{DoxyCode}
\hypertarget{_particle-_scripts_ColourImage-Affector}{}\paragraph{Colour\+Image Affector}\label{_particle-_scripts_ColourImage-Affector}
This is another affector that modifies the colour of particles in flight, but instead of programmatically defining colours, the colours are taken from a specified image file. The range of colour values begins from the left side of the image and move to the right over the lifetime of the particle, therefore only the horizontal dimension of the image is used. Its extra attributes are\+:


\begin{DoxyDescription}
\item[image ]

The start of a range of rotation speed to be assigned to emitted particles.~\newline
     format\+: image $<$image\+\_\+name$>$~\newline
 example\+: image rainbow.\+png~\newline
 default\+: none~\newline



\end{DoxyDescription}

To create a Colour\+Image affector, include a section like this within your particle system script\+:


\begin{DoxyCode}
affector ColourImage
\{
    \textcolor{comment}{// Settings go here}
\}
\end{DoxyCode}
\hypertarget{_particle-_scripts_DeflectorPlane-Affector}{}\paragraph{Deflector\+Plane Affector}\label{_particle-_scripts_DeflectorPlane-Affector}
This affector defines a plane which deflects particles which collide with it. The attributes are\+:


\begin{DoxyDescription}
\item[plane\+\_\+point ]

A point on the deflector plane. Together with the normal vector it defines the plane.~\newline
 default\+: plane\+\_\+point 0 0 0~\newline



\item[plane\+\_\+normal ]

The normal vector of the deflector plane. Together with the point it defines the plane.~\newline
 default\+: plane\+\_\+normal 0 1 0~\newline



\item[bounce ]

The amount of bouncing when a particle is deflected. 0 means no deflection and 1 stands for 100 percent reflection.~\newline
 default\+: bounce 1.\+0


\end{DoxyDescription}\hypertarget{_particle-_scripts_DirectionRandomiser-Affector}{}\paragraph{Direction\+Randomiser Affector}\label{_particle-_scripts_DirectionRandomiser-Affector}
This affector applies randomness to the movement of the particles. Its extra attributes are\+:


\begin{DoxyDescription}
\item[randomness ]

The amount of randomness to introduce in each axial direction.~\newline
 example\+: randomness 5~\newline
 default\+: randomness 1~\newline



\item[scope ]

The percentage of particles affected in each run of the affector.~\newline
 example\+: scope 0.\+5~\newline
 default\+: scope 1.\+0~\newline



\item[keep\+\_\+velocity ]

Determines whether the velocity of particles is unchanged.~\newline
 example\+: keep\+\_\+velocity true~\newline
 default\+: keep\+\_\+velocity false~\newline



\end{DoxyDescription}\hypertarget{Overlay-Scripts}{}\subsection{Overlay Scripts}\label{Overlay-Scripts}
Overlay scripts offer you the ability to define overlays in a script which can be reused easily. Whilst you could set up all overlays for a scene in code using the methods of the Scene\+Manager, Overlay and Overlay\+Element classes, in practice it’s a bit unwieldy. Instead you can store overlay definitions in text files which can then be loaded whenever required.


\begin{DoxyCode}
\textcolor{comment}{// The name of the overlay comes first}
overlay MyOverlays/ANewOverlay
\{
    zorder 200

    overlay\_element MyOverlayElements/TestPanel Panel
    \{
        \textcolor{comment}{// Center it horizontally, put it at the top}
        left 0.25
        top 0
        width 0.5
        height 0.1
        material MyMaterials/APanelMaterial

        \textcolor{comment}{// Another panel nested in this one}
        overlay\_element MyOverlayElements/AnotherPanel Panel
        \{
             left 0
             top 0
             width 0.1
             height 0.1
             material MyMaterials/NestedPanel
        \}
    \}
\}
\end{DoxyCode}


The above example defines a single overlay called ’\+My\+Overlays/\+A\+New\+Overlay’, with 2 panels in it, one nested under the other. It uses relative metrics (the default if no metrics\+\_\+mode option is found).

\begin{DoxyNote}{Note}
Overlays do not yet use the generic \hyperlink{class_ogre_1_1_script_compiler}{Ogre\+::\+Script\+Compiler} so, \hyperlink{_scripts_Advanced-Script-Inheritance}{Advanced Script Inheritance} and \hyperlink{_scripts_Script-Variables}{Script Variables} are not available.
\end{DoxyNote}
The overlay itself only has a single property ’zorder’ which determines how ’high’ it is in the stack of overlays if more than one is displayed at the same time. Overlays with higher zorder values are displayed on top.\hypertarget{_overlay-_scripts_Adding-elements-to-the-overlay}{}\subsubsection{Adding elements to the overlay}\label{_overlay-_scripts_Adding-elements-to-the-overlay}
Within an overlay, you can include any number of 2D or 3D elements. You do this by defining nested ’overlay\+\_\+element’ blocks.

\subsection*{’overlay\+\_\+element’ blocks}

These are delimited by curly braces. The format for the header preceding the first brace is\+:

overlay\+\_\+element $<$instance\+\_\+name$>$ $<$type\+\_\+name$>$ \mbox{[}\+: $<$template\+\_\+name$>$\mbox{]}~\newline
 \{ ...


\begin{DoxyDescription}
\item[type\+\_\+name ]

Must resolve to the name of a Overlay\+Element type which has been registered with the Overlay\+Manager. Plugins register with the Overlay\+Manager to advertise their ability to create elements, and at this time advertise the name of the type. O\+G\+RE comes preconfigured with types ’\+Panel’, ’\+Border\+Panel’ and ’\+Text\+Area’.


\item[instance\+\_\+name ]

Must be a name unique among all other elements / containers by which to identify the element. Note that you can obtain a pointer to any named element by calling Overlay\+Manager\+::get\+Singleton().get\+Overlay\+Element(name).


\item[template\+\_\+name ]

Optional template on which to base this item. See templates.


\end{DoxyDescription}

The properties which can be included within the braces depend on the custom type. However the following are always valid\+:


\begin{DoxyItemize}
\item \href{#metrics_005fmode}{\tt metrics\+\_\+mode}
\item \href{#horz_005falign}{\tt horz\+\_\+align}
\item \href{#vert_005falign}{\tt vert\+\_\+align}
\item \href{#left}{\tt left}
\item \href{#overlaytopelement}{\tt top}
\item \href{#width}{\tt width}
\item \href{#height}{\tt height}
\item \href{#overlay_005fmaterial}{\tt material}
\item \href{#caption}{\tt caption}
\end{DoxyItemize}\hypertarget{_overlay-_scripts_Templates}{}\subsubsection{Templates}\label{_overlay-_scripts_Templates}
You can use templates to create numerous elements with the same properties. A template is an abstract element and it is not added to an overlay. It acts as a base class that elements can inherit and get its default properties. The template element is created in the topmost scope -\/ it is N\+OT specified in an Overlay. It is recommended that you define templates in a separate overlay though this is not essential. Having templates defined in a separate file will allow different look \& feels to be easily substituted.

Elements can inherit a template in a similar way to C++ inheritance -\/ by using the \+: operator on the element definition. The \+: operator is placed after the closing bracket of the name (separated by a space). The name of the template to inherit is then placed after the \+: operator (also separated by a space).

A template can contain template children which are created when the template is subclassed and instantiated.


\begin{DoxyCode}
overlay\_element MyTemplates/BasicBorderPanel BorderPanel
\{
    left 0
    top 0
    width 1
    height 1

\textcolor{comment}{// setup the texture UVs for a borderpanel}

\textcolor{comment}{// do this in a template so it doesn't need to be redone everywhere}
    material Core/StatsBlockCenter
    border\_size 0.05 0.05 0.06665 0.06665
    border\_material Core/StatsBlockBorder
    border\_topleft\_uv 0.0000 1.0000 0.1914 0.7969
    border\_top\_uv 0.1914 1.0000 0.8086 0.7969
    border\_topright\_uv 0.8086 1.0000 1.0000 0.7969
    border\_left\_uv 0.0000 0.7969 0.1914 0.2148
    border\_right\_uv 0.8086 0.7969 1.0000 0.2148
    border\_bottomleft\_uv 0.0000 0.2148 0.1914 0.0000
    border\_bottom\_uv 0.1914 0.2148 0.8086 0.0000
    border\_bottomright\_uv 0.8086 0.2148 1.0000 0.0000
\}
overlay\_element MyTemplates/BasicButton Button : MyTemplates/BasicBorderPanel
\{
    left 0.82
    top 0.45
    width 0.16
    height 0.13
    material Core/StatsBlockCenter
    border\_up\_material Core/StatsBlockBorder/Up
    border\_down\_material Core/StatsBlockBorder/Down
\}
overlay\_element MyTemplates/BasicText TextArea
\{
    font\_name \hyperlink{namespace_ogre}{Ogre}
    char\_height 0.08
    colour\_top 1 1 0
    colour\_bottom 1 0.2 0.2
    left 0.03
    top 0.02
    width 0.12
    height 0.09
\}

overlay MyOverlays/AnotherOverlay
\{
    zorder 490
    overlay\_element MyElements/BackPanel BorderPanel : MyTemplates/BasicBorderPanel
    \{
        left 0
        top 0
        width 1
        height 1

        overlay\_element MyElements/HostButton Button : MyTemplates/BasicButton
        \{
            left 0.82
            top 0.45
            caption MyTemplates/BasicText HOST
        \}

        overlay\_element MyElements/JoinButton Button : MyTemplates/BasicButton
        \{
            left 0.82
            top 0.60
            caption MyTemplates/BasicText JOIN
        \}
    \}
\}
\end{DoxyCode}


The above example uses templates to define a button. Note that the button template inherits from the border\+Panel template. This reduces the number of attributes needed to instantiate a button.

Also note that the instantiate of a Button needs a template name for the caption attribute. So templates can also be used by elements that need dynamic creation of children elements (the button creates a Text\+Area\+Element in this case for its caption).

See \href{#OverlayElement-Attributes}{\tt Overlay\+Element Attributes}, \href{#Standard-OverlayElements}{\tt Standard Overlay\+Elements}

\label{_OverlayElement-Attributes}%
 \label{_OverlayElement-Attributes-1}%


\subsection*{Overlay\+Element Attributes}

These attributes are valid within the braces of a ’container’ or ’element’ block in an overlay script. They must each be on their own line. Ordering is unimportant.

\label{_metrics_005fmode}%
\label{_metrics_005fmode-1}%


\subsection*{metrics\+\_\+mode}

Sets the units which will be used to size and position this element.

\begin{DoxyParagraph}{}
Format\+: metrics\+\_\+mode $<$pixels$\vert$relative$>$~\newline
 Example\+: metrics\+\_\+mode pixels~\newline

\end{DoxyParagraph}
This can be used to change the way that all measurement attributes in the rest of this element are interpreted. In relative mode, they are interpreted as being a parametric value from 0 to 1, as a proportion of the width / height of the screen. In pixels mode, they are simply pixel offsets. \begin{DoxyParagraph}{}
Default\+: metrics\+\_\+mode relative~\newline

\end{DoxyParagraph}
\label{_horz_005falign}%
\label{_horz_005falign-1}%


\subsection*{horz\+\_\+align}

Sets the horizontal alignment of this element, in terms of where the horizontal origin is. \begin{DoxyParagraph}{}
Format\+: horz\+\_\+align $<$left$\vert$center$\vert$right$>$~\newline
 Example\+: horz\+\_\+align center
\end{DoxyParagraph}
This can be used to change where the origin is deemed to be for the purposes of any horizontal positioning attributes of this element. By default the origin is deemed to be the left edge of the screen, but if you change this you can center or right-\/align your elements. Note that setting the alignment to center or right does not automatically force your elements to appear in the center or the right edge, you just have to treat that point as the origin and adjust your coordinates appropriately. This is more flexible because you can choose to position your element anywhere relative to that origin. For example, if your element was 10 pixels wide, you would use a ’left’ property of -\/10 to align it exactly to the right edge, or -\/20 to leave a gap but still make it stick to the right edge.

Note that you can use this property in both relative and pixel modes, but it is most useful in pixel mode. \begin{DoxyParagraph}{}
Default\+: horz\+\_\+align left~\newline

\end{DoxyParagraph}
\label{_vert_005falign}%
\label{_vert_005falign-1}%


\subsection*{vert\+\_\+align}

Sets the vertical alignment of this element, in terms of where the vertical origin is. \begin{DoxyParagraph}{}
Format\+: vert\+\_\+align $<$top$\vert$center$\vert$bottom$>$~\newline
 Example\+: vert\+\_\+align center
\end{DoxyParagraph}
This can be used to change where the origin is deemed to be for the purposes of any vertical positioning attributes of this element. By default the origin is deemed to be the top edge of the screen, but if you change this you can center or bottom-\/align your elements. Note that setting the alignment to center or bottom does not automatically force your elements to appear in the center or the bottom edge, you just have to treat that point as the origin and adjust your coordinates appropriately. This is more flexible because you can choose to position your element anywhere relative to that origin. For example, if your element was 50 pixels high, you would use a ’top’ property of -\/50 to align it exactly to the bottom edge, or -\/70 to leave a gap but still make it stick to the bottom edge.

Note that you can use this property in both relative and pixel modes, but it is most useful in pixel mode. \begin{DoxyParagraph}{}
Default\+: vert\+\_\+align top~\newline

\end{DoxyParagraph}
\label{_left}%
\label{_left-1}%


\subsection*{left}

Sets the horizontal position of the element relative to it’s parent. \begin{DoxyParagraph}{}
Format\+: left $<$value$>$~\newline
 Example\+: left 0.\+5
\end{DoxyParagraph}
Positions are relative to the parent (the top-\/left of the screen if the parent is an overlay, the top-\/left of the parent otherwise) and are expressed in terms of a proportion of screen size. Therefore 0.\+5 is half-\/way across the screen. \begin{DoxyParagraph}{}
Default\+: left 0~\newline

\end{DoxyParagraph}
\label{_overlaytopelement}%
\label{_top}%


\subsection*{top}

Sets the vertical position of the element relative to it’s parent. \begin{DoxyParagraph}{}
Format\+: top $<$value$>$~\newline
 Example\+: top 0.\+5
\end{DoxyParagraph}
Positions are relative to the parent (the top-\/left of the screen if the parent is an overlay, the top-\/left of the parent otherwise) and are expressed in terms of a proportion of screen size. Therefore 0.\+5 is half-\/way down the screen. \begin{DoxyParagraph}{}
Default\+: top 0~\newline

\end{DoxyParagraph}
\label{_width}%
\label{_width-1}%


\subsection*{width}

Sets the width of the element as a proportion of the size of the screen. \begin{DoxyParagraph}{}
Format\+: width $<$value$>$~\newline
 Example\+: width 0.\+25
\end{DoxyParagraph}
Sizes are relative to the size of the screen, so 0.\+25 is a quarter of the screen. Sizes are not relative to the parent; this is common in windowing systems where the top and left are relative but the size is absolute. \begin{DoxyParagraph}{}
Default\+: width 1~\newline

\end{DoxyParagraph}
\label{_height}%
\label{_height-1}%


\subsection*{height}

Sets the height of the element as a proportion of the size of the screen. \begin{DoxyParagraph}{}
Format\+: height $<$value$>$~\newline
 Example\+: height 0.\+25
\end{DoxyParagraph}
Sizes are relative to the size of the screen, so 0.\+25 is a quarter of the screen. Sizes are not relative to the parent; this is common in windowing systems where the top and left are relative but the size is absolute. \begin{DoxyParagraph}{}
Default\+: height 1~\newline

\end{DoxyParagraph}
\label{_overlay_005fmaterial}%
\label{_material-3}%


\subsection*{material}

Sets the name of the material to use for this element. \begin{DoxyParagraph}{}
Format\+: material $<$name$>$~\newline
 Example\+: material Examples/\+Test\+Material
\end{DoxyParagraph}
This sets the base material which this element will use. Each type of element may interpret this differently; for example the O\+G\+RE element ’\+Panel’ treats this as the background of the panel, whilst ’\+Border\+Panel’ interprets this as the material for the center area only. Materials should be defined in .material scripts. Note that using a material in an overlay element automatically disables lighting and depth checking on this material. Therefore you should not use the same material as is used for real 3D objects for an overlay. \begin{DoxyParagraph}{}
Default\+: none~\newline

\end{DoxyParagraph}
\label{_caption}%
\label{_caption-1}%


\subsection*{caption}

Sets a text caption for the element. \begin{DoxyParagraph}{}
Format\+: caption $<$string$>$~\newline
 Example\+: caption This is a caption
\end{DoxyParagraph}
Not all elements support captions, so each element is free to disregard this if it wants. However, a general text caption is so common to many elements that it is included in the generic interface to make it simpler to use. This is a common feature in G\+UI systems. \begin{DoxyParagraph}{}
Default\+: blank
\end{DoxyParagraph}
\label{_rotation}%
\label{_rotation-1}%


\subsection*{rotation}

Sets the rotation of the element. \begin{DoxyParagraph}{}
Format\+: rotation $<$angle\+\_\+in\+\_\+degrees$>$ $<$axis\+\_\+x$>$ $<$axis\+\_\+y$>$ $<$axis\+\_\+z$>$ Example\+: rotation 30 0 0 1 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Default\+: none
\end{DoxyParagraph}
\hypertarget{_overlay-_scripts_Standard-OverlayElements}{}\subsubsection{Standard Overlay\+Elements}\label{_overlay-_scripts_Standard-OverlayElements}
Although O\+G\+R\+E’s Overlay\+Element and Overlay\+Container classes are designed to be extended by applications developers, there are a few elements which come as standard with \hyperlink{namespace_ogre}{Ogre}. These include\+:


\begin{DoxyItemize}
\item \href{#Panel}{\tt Panel}
\item \href{#BorderPanel}{\tt Border\+Panel}
\item \href{#TextArea}{\tt Text\+Area}
\end{DoxyItemize}

This section describes how you define their custom attributes in an .overlay script, but you can also change these custom properties in code if you wish. You do this by calling set\+Parameter(param, value). You may wish to use the String\+Converter class to convert your types to and from strings.\hypertarget{_overlay-_scripts_Panel}{}\paragraph{Panel}\label{_overlay-_scripts_Panel}
This is the most bog-\/standard container you can use. It is a rectangular area which can contain other elements (or containers) and may or may not have a background, which can be tiled however you like. The background material is determined by the material attribute, but is only displayed if transparency is off.


\begin{DoxyParams}{Parameters}
{\em transparent} & {\bfseries $<$true $\vert$ false$>$} If set to ’true’ the panel is transparent and is not rendered itself, it is just used as a grouping level for it’s children.\\
\hline
{\em tiling} & {\bfseries $<$layer$>$ $<$x\+\_\+tile$>$ $<$y\+\_\+tile$>$} Sets the number of times the texture(s) of the material are tiled across the panel in the x and y direction. $<$layer$>$ is the texture layer, from 0 to the number of texture layers in the material minus one. By setting tiling per layer you can create some nice multitextured backdrops for your panels, this works especially well when you animate one of the layers.\\
\hline
{\em uv\+\_\+coords} & {\bfseries $<$topleft\+\_\+u$>$ $<$topleft\+\_\+v$>$ $<$bottomright\+\_\+u$>$ $<$bottomright\+\_\+v$>$} Sets the texture coordinates to use for this panel.\\
\hline
\end{DoxyParams}
\hypertarget{_overlay-_scripts_BorderPanel}{}\paragraph{Border\+Panel}\label{_overlay-_scripts_BorderPanel}
This is a slightly more advanced version of Panel, where instead of just a single flat panel, the panel has a separate border which resizes with the panel. It does this by taking an approach very similar to the use of H\+T\+ML tables for bordered content\+: the panel is rendered as 9 square areas, with the center area being rendered with the main material (as with Panel) and the outer 8 areas (the 4 corners and the 4 edges) rendered with a separate border material. The advantage of rendering the corners separately from the edges is that the edge textures can be designed so that they can be stretched without distorting them, meaning the single texture can serve any size panel.


\begin{DoxyParams}{Parameters}
{\em border\+\_\+size} & {\bfseries $<$left$>$ $<$right$>$ $<$top$>$ $<$bottom$>$} The size of the border at each edge, as a proportion of the size of the screen. This lets you have different size borders at each edge if you like, or you can use the same value 4 times to create a constant size border.\\
\hline
{\em border\+\_\+material} & {\bfseries $<$name$>$} The name of the material to use for the border. This is normally a different material to the one used for the center area, because the center area is often tiled which means you can’t put border areas in there. You must put all the images you need for all the corners and the sides into a single texture.\\
\hline
{\em border\+\_\+topleft\+\_\+uv} & {\bfseries $<$u1$>$ $<$v1$>$ $<$u2$>$ $<$v2$>$} \mbox{[}also border\+\_\+topright\+\_\+uv, border\+\_\+bottomleft\+\_\+uv, border\+\_\+bottomright\+\_\+uv\mbox{]}; The texture coordinates to be used for the corner areas of the border. 4 coordinates are required, 2 for the top-\/left corner of the square, 2 for the bottom-\/right of the square.\\
\hline
{\em border\+\_\+left\+\_\+uv} & {\bfseries $<$u1$>$ $<$v1$>$ $<$u2$>$ $<$v2$>$} \mbox{[}also border\+\_\+right\+\_\+uv, border\+\_\+top\+\_\+uv, border\+\_\+bottom\+\_\+uv\mbox{]}; The texture coordinates to be used for the edge areas of the border. 4 coordinates are required, 2 for the top-\/left corner, 2 for the bottom-\/right. Note that you should design the texture so that the left \& right edges can be stretched / squashed vertically and the top and bottom edges can be stretched / squashed horizontally without detrimental effects.\\
\hline
\end{DoxyParams}
\hypertarget{_overlay-_scripts_TextArea}{}\paragraph{Text\+Area}\label{_overlay-_scripts_TextArea}
This is a generic element that you can use to render text. It uses fonts which can be defined in code using the Font\+Manager and Font classes, or which have been predefined in .fontdef files. See the font definitions section for more information.


\begin{DoxyParams}{Parameters}
{\em font\+\_\+name} & {\bfseries $<$name$>$} The name of the font to use. This font must be defined in a .fontdef file to ensure it is available at scripting time.\\
\hline
{\em char\+\_\+height} & {\bfseries $<$height$>$} The height of the letters as a proportion of the screen height. Character widths may vary because O\+G\+RE supports proportional fonts, but will be based on this constant height.\\
\hline
{\em colour} & {\bfseries $<$red$>$ $<$green$>$ $<$blue$>$} A solid colour to render the text in. Often fonts are defined in monochrome, so this allows you to colour them in nicely and use the same texture for multiple different coloured text areas. The colour elements should all be expressed as values between 0 and 1. If you use predrawn fonts which are already full colour then you don’t need this.\\
\hline
{\em colour\+\_\+bottom} & {\bfseries $<$red$>$ $<$green$>$ $<$blue$>$} \\
\hline
{\em colour\+\_\+top} & {\bfseries $<$red$>$ $<$green$>$ $<$blue$>$} As an alternative to a solid colour, you can colour the text differently at the top and bottom to create a gradient colour effect which can be very effective.\\
\hline
{\em alignment} & {\bfseries $<$left $\vert$ center $\vert$ right$>$} Sets the horizontal alignment of the text. This is different from the horz\+\_\+align parameter.\\
\hline
{\em space\+\_\+width} & {\bfseries $<$width$>$} Sets the width of a space in relation to the screen. \\
\hline
\end{DoxyParams}
\hypertarget{Font-Definition-Scripts}{}\subsection{Font Definition Scripts}\label{Font-Definition-Scripts}
\hyperlink{namespace_ogre}{Ogre} uses texture-\/based fonts to render the \hyperlink{class_ogre_1_1_text_area_overlay_element}{Ogre\+::\+Text\+Area\+Overlay\+Element}. You can also use the Font object for your own purpose if you wish. The final form of a font is a Material object generated by the font, and a set of ’glyph’ (character) texture coordinate information.

There are 2 ways you can get a font into O\+G\+RE\+:


\begin{DoxyEnumerate}
\item Design a font texture yourself using an art package or font generator tool
\item Ask O\+G\+RE to generate a font texture based on a truetype font
\end{DoxyEnumerate}

The former gives you the most flexibility and the best performance (in terms of startup times), but the latter is convenient if you want to quickly use a font without having to generate the texture yourself. I suggest prototyping using the latter and change to the former for your final solution.

All font definitions are held in .fontdef files, which are parsed by the system at startup time. Each .fontdef file can contain multiple font definitions. The basic format of an entry in the .fontdef file is\+:


\begin{DoxyCode}
font <font\_name>
\{
    type <image | truetype>
    source <image file | truetype font file>
    ...
    ... custom attributes depending on type
\}
\end{DoxyCode}


\label{_Using-an-existing-font-texture}%


\section*{Using an existing font texture}

If you have one or more artists working with you, no doubt they can produce you a very nice font texture. O\+G\+RE supports full colour font textures, or alternatively you can keep them monochrome / greyscale and use Text\+Area’s colouring feature. Font textures should always have an alpha channel, preferably an 8-\/bit alpha channel such as that supported by T\+GA and P\+NG files, because it can result in much nicer edges. To use an existing texture, here are the settings you need\+:


\begin{DoxyParams}{Parameters}
{\em type} & {\bfseries image} This just tells O\+G\+RE you want a pre-\/drawn font.\\
\hline
{\em source} & {\bfseries $<$filename$>$} This is the name of the image file you want to load. This will be loaded from the standard Texture\+Manager resource locations and can be of any type O\+G\+RE supports, although J\+P\+EG is not recommended because of the lack of alpha and the lossy compression. I recommend P\+NG format which has both good lossless compression and an 8-\/bit alpha channel.\\
\hline
{\em glyph} & {\bfseries $<$character$>$ $<$u1$>$ $<$v1$>$ $<$u2$>$ $<$v2$>$} This provides the texture coordinates for the specified character. You must repeat this for every character you have in the texture. The first 2 numbers are the x and y of the top-\/left corner, the second two are the x and y of the bottom-\/right corner. Note that you really should use a common height for all characters, but widths can vary because of proportional fonts. ’character’ is either an A\+S\+C\+II character for non-\/extended 7-\/bit A\+S\+C\+II, or for extended glyphs, a unicode decimal value, which is identified by preceding the number with a ’u’ -\/ e.\+g. ’u0546’ denotes unicode value 546.\\
\hline
\end{DoxyParams}
A note for Windows users\+: I recommend using Bitmap\+Font\+Builder (\href{http://www.lmnopc.com/bitmapfontbuilder/}{\tt http\+://www.\+lmnopc.\+com/bitmapfontbuilder/}), a free tool which will generate a texture and export character widths for you, you can find a tool for converting the binary output from this into ’glyph’ lines in the Tools folder.~\newline


\label{_Generating-a-font-texture}%


\section*{Generating a font texture}

You can also generate font textures on the fly using truetype fonts. I don’t recommend heavy use of this in production work because rendering the texture can take a several seconds per font which adds to the loading times. However it is a very nice way of quickly getting text output in a font of your choice.

Here are the attributes you need to supply\+:


\begin{DoxyParams}{Parameters}
{\em type} & {\bfseries truetype} Tells O\+G\+RE to generate the texture from a font\\
\hline
{\em source} & {\bfseries $<$ttf file$>$} The name of the ttf file to load. This will be searched for in the common resource locations and in any resource locations added to Font\+Manager.\\
\hline
{\em size} & {\bfseries $<$size\+\_\+in\+\_\+points$>$} The size at which to generate the font, in standard points. Note this only affects how big the characters are in the font texture, not how big they are on the screen. You should tailor this depending on how large you expect to render the fonts because generating a large texture will result in blurry characters when they are scaled very small (because of the mipmapping), and conversely generating a small font will result in blocky characters if large text is rendered.\\
\hline
{\em resolution} & {\bfseries $<$dpi$>$} The resolution in dots per inch, this is used in conjunction with the point size to determine the final size. 72 / 96 dpi is normal.\\
\hline
{\em antialias\+\_\+colour} & {\bfseries $<$true$\vert$false$>$} This is an optional flag, which defaults to ’false’. The generator will antialias the font by default using the alpha component of the texture, which will look fine if you use alpha blending to render your text (this is the default assumed by Text\+Area\+Overlay\+Element for example). If, however you wish to use a colour based blend like add or modulate in your own code, you should set this to ’true’ so the colour values are anti-\/aliased too. If you set this to true and use alpha blending, you’ll find the edges of your font are antialiased too quickly resulting in a ’thin’ look to your fonts, because not only is the alpha blending the edges, the colour is fading too. Leave this option at the default if in doubt.\\
\hline
{\em code\+\_\+points} & {\bfseries nn-\/nn \mbox{[}nn-\/nn\mbox{]} ..} This directive allows you to specify which unicode code points should be generated as glyphs into the font texture. If you don’t specify this, code points 33-\/126 will be generated by default which covers the A\+S\+C\+II glyphs. If you use this flag, you should specify a space-\/separated list of inclusive code point ranges of the form ’start-\/end’. Numbers must be decimal.\\
\hline
{\em character\+\_\+spacer} & {\bfseries $<$spacing\+\_\+in\+\_\+points$>$} This option can be useful for fonts that are atypically wide, e.\+g. calligraphy fonts, where you may see artifacts from characters overlapping. The default value is 5.\\
\hline
\end{DoxyParams}
You can also create new fonts at runtime by using the Font\+Manager if you wish. \hypertarget{High-level-Programs}{}\section{High-\/level Programs}\label{High-level-Programs}
Support for high level vertex and fragment programs is provided through plugins; this is to make sure that an application using O\+G\+RE can use as little or as much of the high-\/level program functionality as they like. O\+G\+RE currently supports 3 high-\/level program types, Cg (\href{#Cg}{\tt Cg}) (an A\+P\+I-\/ and card-\/independent, high-\/level language which lets you write programs for both Open\+GL and DirectX for lots of cards), DirectX 9 High-\/\+Level Shader Language (\href{#HLSL}{\tt H\+L\+SL}), and Open\+GL Shader Language (\href{#GLSL}{\tt G\+L\+SL}). H\+L\+SL can only be used with the DirectX rendersystem, and G\+L\+SL can only be used with the GL rendersystem. Cg can be used with both, although experience has shown that more advanced programs, particularly fragment programs which perform a lot of texture fetches, can produce better code in the rendersystem-\/specific shader language.

One way to support both H\+L\+SL and G\+L\+SL is to include separate techniques in the material script, each one referencing separate programs. However, if the programs are basically the same, with the same parameters, and the techniques are complex this can bloat your material scripts with duplication fairly quickly. Instead, if the only difference is the language of the vertex \& fragment program you can use O\+G\+R\+E’s \href{#Unified-High_002dlevel-Programs}{\tt Unified High-\/level Programs} to automatically pick a program suitable for your rendersystem whilst using a single technique.\hypertarget{_high-level-_programs_Cg}{}\subsection{Cg programs}\label{_high-level-_programs_Cg}
In order to define Cg programs, you have to have to load Plugin\+\_\+\+Cg\+Program\+Manager.\+so/.dll at startup, either through plugins.\+cfg or through your own plugin loading code. They are very easy to define\+:


\begin{DoxyCode}
fragment\_program myCgFragmentProgram cg
\{
    source myCgFragmentProgram.cg
    entry\_point main
    profiles ps\_2\_0 arbfp1
\}
\end{DoxyCode}


There are a few differences between this and the assembler program -\/ to begin with, we declare that the fragment program is of type {\ttfamily cg} rather than {\ttfamily asm}, which indicates that it’s a high-\/level program using Cg. The {\ttfamily source} parameter is the same, except this time it’s referencing a Cg source file instead of a file of assembler. Here is where things start to change. Firstly, we need to define an {\ttfamily entry\+\_\+point}, which is the name of a function in the Cg program which will be the first one called as part of the fragment program. Unlike assembler programs, which just run top-\/to-\/bottom, Cg programs can include multiple functions and as such you must specify the one which start the ball rolling. Next, instead of a fixed {\ttfamily syntax} parameter, you specify one or more {\ttfamily profiles}; profiles are how Cg compiles a program down to the low-\/level assembler. The profiles have the same names as the assembler syntax codes mentioned above; the main difference is that you can list more than one, thus allowing the program to be compiled down to more low-\/level syntaxes so you can write a single high-\/level program which runs on both D3D and GL. You are advised to just enter the simplest profiles under which your programs can be compiled in order to give it the maximum compatibility. The ordering also matters; if a card supports more than one syntax then the one listed first will be used.

Lastly, there is a final option called {\ttfamily compile\+\_\+arguments}, where you can specify arguments exactly as you would to the cgc command-\/line compiler, should you wish to.\hypertarget{_high-level-_programs_HLSL}{}\subsection{Direct\+X9 H\+L\+SL}\label{_high-level-_programs_HLSL}
Direct\+X9 H\+L\+SL has a very similar language syntax to Cg but is tied to the DirectX A\+PI. The only benefit over Cg is that it only requires the DirectX 9 render system plugin, not any additional plugins. Declaring a Direct\+X9 H\+L\+SL program is very similar to Cg. Here’s an example\+:


\begin{DoxyCode}
vertex\_program myHLSLVertexProgram hlsl
\{
    source myHLSLVertexProgram.txt
    entry\_point main
    target vs\_2\_0
\}
\end{DoxyCode}


As you can see, the main syntax is almost identical, except that instead of {\ttfamily profiles} with a list of assembler formats, you have a {\ttfamily target} parameter which allows a single assembler target to be specified -\/ obviously this has to be a DirectX assembler format syntax code.

{\bfseries Important Matrix Ordering Note\+:} One thing to bear in mind is that H\+L\+SL allows you to use 2 different ways to multiply a vector by a matrix -\/ mul(v,m) or mul(m,v). The only difference between them is that the matrix is effectively transposed. You should use mul(m,v) with the matrices passed in from \hyperlink{namespace_ogre}{Ogre} -\/ this agrees with the shaders produced from tools like Render\+Monkey, and is consistent with Cg too, but disagrees with the Dx9 S\+DK and FX Composer which use mul(v,m) -\/ you will have to switch the parameters to mul() in those shaders.

Note that if you use the float3x4 / matrix3x4 type in your shader, bound to an O\+G\+RE auto-\/definition (such as bone matrices) you should use the {\ttfamily column\+\_\+major\+\_\+matrices = false} option (discussed below) in your program definition. This is because O\+G\+RE passes float3x4 as row-\/major to save constant space (3 float4’s rather than 4 float4’s with only the top 3 values used) and this tells O\+G\+RE to pass all matrices like this, so that you can use mul(m,v) consistently for all calculations. O\+G\+RE will also to tell the shader to compile in row-\/major form (you don’t have to set the /\+Zpr compile option or \#pragma pack(row-\/major) option, O\+G\+RE does this for you). Note that passing bones in float4x3 form is not supported by O\+G\+RE, but you don’t need it given the above.

{\bfseries Advanced options}~\newline



\begin{DoxyDescription}
\item[preprocessor\+\_\+defines $<$defines$>$ ]

This allows you to define symbols which can be used inside the H\+L\+SL shader code to alter the behaviour (through \#ifdef or \#if clauses). Definitions are separated by ’;’ or ’,’ and may optionally have a ’=’ operator within them to specify a definition value. Those without an ’=’ will implicitly have a definition of 1.


\item[column\+\_\+major\+\_\+matrices $<$true$\vert$false$>$ ]

The default for this option is ’true’ so that O\+G\+RE passes matrices auto-\/bound matrices in a form where mul(m,v) works. Setting this option to false does 2 things -\/ it transpose auto-\/bound 4x4 matrices and also sets the /\+Zpr (row-\/major) option on the shader compilation. This means you can still use mul(m,v), but the matrix layout is row-\/major instead. This is only useful if you need to use bone matrices (float3x4) in a shader since it saves a float4 constant for every bone involved.


\item[optimisation\+\_\+level $<$opt$>$ ]

Set the optimisation level, which can be one of ’default’, ’none’, ’0’, ’1’, ’2’, or ’3’. This corresponds to the /O parameter of fxc.\+exe, except that in ’default’ mode, optimisation is disabled in debug mode and set to 1 in release mode (fxc.\+exe uses 1 all the time). Unsurprisingly the default value is ’default’. You may want to change this if you want to tweak the optimisation, for example if your shader gets so complex that it will not longer compile without some minimum level of optimisation.


\end{DoxyDescription}\hypertarget{_high-level-_programs_GLSL}{}\subsection{Open\+G\+L G\+L\+SL}\label{_high-level-_programs_GLSL}
Open\+GL G\+L\+SL has a similar language syntax to H\+L\+SL but is tied to the Open\+GL A\+PI. The are a few benefits over Cg in that it only requires the Open\+GL render system plugin, not any additional plugins. Declaring a Open\+GL G\+L\+SL program is similar to Cg but simpler. Here’s an example\+:


\begin{DoxyCode}
vertex\_program myGLSLVertexProgram glsl
\{
    source myGLSLVertexProgram.txt
\}
\end{DoxyCode}


In G\+L\+SL, no entry point needs to be defined since it is always {\ttfamily main()} and there is no target definition since G\+L\+SL source is compiled into native G\+PU code and not intermediate assembly.

G\+L\+SL supports the use of modular shaders. This means you can write G\+L\+SL external functions that can be used in multiple shaders.


\begin{DoxyCode}
vertex\_program myExternalGLSLFunction1 glsl
\{
    source myExternalGLSLfunction1.txt
\}

vertex\_program myExternalGLSLFunction2 glsl
\{
    source myExternalGLSLfunction2.txt
\}

vertex\_program myGLSLVertexProgram1 glsl
\{
    source myGLSLfunction.txt
    attach myExternalGLSLFunction1 myExternalGLSLFunction2
\}

vertex\_program myGLSLVertexProgram2 glsl
\{
    source myGLSLfunction.txt
    attach myExternalGLSLFunction1
\}
\end{DoxyCode}


External G\+L\+SL functions are attached to the program that needs them by using {\ttfamily attach} and including the names of all external programs required on the same line separated by spaces. This can be done for both vertex and fragment programs.\hypertarget{_high-level-_programs_GLSL-Texture-Samplers}{}\subsubsection{G\+L\+S\+L Texture Samplers}\label{_high-level-_programs_GLSL-Texture-Samplers}
To pass texture unit index values from the material script to texture samplers in glsl use {\ttfamily int} type named parameters. See the example below\+:~\newline


excerpt from G\+L\+SL example.\+frag source\+:


\begin{DoxyCode}
varying vec2 UV;
uniform sampler2D diffuseMap;

\textcolor{keywordtype}{void} main(\textcolor{keywordtype}{void})
\{
    gl\_FragColor = texture2D(diffuseMap, UV);
\}
\end{DoxyCode}


In material script\+:


\begin{DoxyCode}
fragment\_program myFragmentShader glsl
\{
  source example.frag
\}

material exampleGLSLTexturing
\{
  technique
  \{
    pass
    \{
      fragment\_program\_ref myFragmentShader
      \{
        param\_named diffuseMap \textcolor{keywordtype}{int} 0
      \}

      texture\_unit 
      \{
        texture myTexture.jpg 2d
      \}
    \}
  \}
\}
\end{DoxyCode}


An index value of 0 refers to the first texture unit in the pass, an index value of 1 refers to the second unit in the pass and so on.\hypertarget{_high-level-_programs_Matrix-parameters}{}\subsubsection{Matrix parameters}\label{_high-level-_programs_Matrix-parameters}
Here are some examples of passing matrices to G\+L\+SL mat2, mat3, mat4 uniforms\+:


\begin{DoxyCode}
material exampleGLSLmatrixUniforms
\{
  technique matrix\_passing
  \{
    pass examples
    \{
      vertex\_program\_ref myVertexShader
      \{
        \textcolor{comment}{// mat4 uniform}
        param\_named OcclusionMatrix matrix4x4 1 0 0 0  0 1 0 0  0 0 1 0  0 0 0 0 
        \textcolor{comment}{// or}
        param\_named ViewMatrix float16 0 1 0 0  0 0 1 0  0 0 0 1  0 0 0 0 

        \textcolor{comment}{// mat3}
        param\_named TextRotMatrix float9 1 0 0  0 1 0  0 0 1  
      \}

      fragment\_program\_ref myFragmentShader
      \{ 
        \textcolor{comment}{// mat2 uniform}
        param\_named skewMatrix float4 0.5 0 -0.5 1.0
      \}
    \}
  \}
\}
\end{DoxyCode}
\hypertarget{_high-level-_programs_Accessing-OpenGL-states-in-GLSL}{}\subsubsection{Accessing Open\+G\+L states in G\+L\+SL}\label{_high-level-_programs_Accessing-OpenGL-states-in-GLSL}
G\+L\+SL can access most of the GL states directly so you do not need to pass these states through \href{#param_005fnamed_005fauto}{\tt param\+\_\+named\+\_\+auto} in the material script. This includes lights, material state, and all the matrices used in the open\+GL state i.\+e. model view matrix, worldview projection matrix etc.

\begin{DoxyNote}{Note}
this is only possible with Open\+GL legacy profiles i.\+e. {\bfseries not} with G\+L3+.
\end{DoxyNote}
\hypertarget{_high-level-_programs_Binding-vertex-attributes}{}\subsubsection{Binding vertex attributes}\label{_high-level-_programs_Binding-vertex-attributes}
G\+L\+SL natively supports automatic binding of the most common incoming per-\/vertex attributes (e.\+g. {\ttfamily gl\+\_\+\+Vertex}, {\ttfamily gl\+\_\+\+Normal}, {\ttfamily gl\+\_\+\+Multi\+Tex\+Coord0} etc). However, there are some which are not automatically bound, which must be declared in the shader using the {\ttfamily attribute $<$type$>$ $<$name$>$} syntax, and the vertex data bound to it by \hyperlink{namespace_ogre}{Ogre}.

\begin{DoxyNote}{Note}
again this is only possible with Open\+GL legacy profiles i.\+e. {\bfseries not} with G\+L3+.
\end{DoxyNote}
In addition to the built in attributes described in section 7.\+3 of the G\+L\+SL manual, \hyperlink{namespace_ogre}{Ogre} supports a number of automatically bound custom vertex attributes. There are some drivers that do not behave correctly when mixing built-\/in vertex attributes like {\ttfamily gl\+\_\+\+Normal} and custom vertex attributes, so for maximum compatibility you should use all custom attributes


\begin{DoxyDescription}
\item[vertex ]

Binds \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00dad04d50e91c2ec5377e610b3f5b9b07f2}{Ogre\+::\+V\+E\+S\+\_\+\+P\+O\+S\+I\+T\+I\+ON}, declare as ’attribute vec4 vertex;’.


\item[normal ]

Binds \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00da1dec7d36a64625348e23af26c9231227}{Ogre\+::\+V\+E\+S\+\_\+\+N\+O\+R\+M\+AL}, declare as ’attribute vec3 normal;’.


\item[colour ]

Binds \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00daabddc327dc0835e75b7622ee81e7f527}{Ogre\+::\+V\+E\+S\+\_\+\+D\+I\+F\+F\+U\+SE}, declare as ’attribute vec4 colour;’.


\item[secondary\+\_\+colour ]

Binds \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00daac8754d6241197a32c19cd72ff1806cc}{Ogre\+::\+V\+E\+S\+\_\+\+S\+P\+E\+C\+U\+L\+AR}, declare as ’attribute vec4 secondary\+\_\+colour;’.


\item[uv0 -\/ uv7 ]

Binds \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00da17abb855311f3a67bc31414cad8d6212}{Ogre\+::\+V\+E\+S\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+C\+O\+O\+R\+D\+I\+N\+A\+T\+ES}, declare as ’attribute vec4 uv0;’. Note that uv6 and uv7 share attributes with tangent and binormal respectively so cannot both be present.


\item[tangent ]

Binds \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00da57d43012049b3ec7b4240b207dd029f2}{Ogre\+::\+V\+E\+S\+\_\+\+T\+A\+N\+G\+E\+NT}, declare as ’attribute vec3 tangent;’.


\item[binormal ]

Binds \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00da2b06bd6ce4e2b9115ab122e35d86502f}{Ogre\+::\+V\+E\+S\+\_\+\+B\+I\+N\+O\+R\+M\+AL}, declare as ’attribute vec3 binormal;’.


\item[blend\+Indices ]

Binds \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00dae54f94c9c9cf553d227c2aab2c499bbf}{Ogre\+::\+V\+E\+S\+\_\+\+B\+L\+E\+N\+D\+\_\+\+I\+N\+D\+I\+C\+ES}, declare as ’attribute vec4 blend\+Indices;’.


\item[blend\+Weights ]

Binds \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00da63d3494547f373f5c4397a41b39cf6a0}{Ogre\+::\+V\+E\+S\+\_\+\+B\+L\+E\+N\+D\+\_\+\+W\+E\+I\+G\+H\+TS}, declare as ’attribute vec4 blend\+Weights;’.


\end{DoxyDescription}\hypertarget{_high-level-_programs_Preprocessor-definitions}{}\subsubsection{Preprocessor definitions}\label{_high-level-_programs_Preprocessor-definitions}
G\+L\+SL supports using preprocessor definitions in your code -\/ some are defined by the implementation, but you can also define your own, say in order to use the same source code for a few different variants of the same technique. In order to use this feature, include preprocessor conditions in your G\+L\+SL code, of the kind \#ifdef S\+Y\+M\+B\+OL, \#if S\+Y\+M\+B\+OL==2 etc. Then in your program definition, use the ’preprocessor\+\_\+defines’ option, following it with a string if definitions. Definitions are separated by ’;’ or ’,’ and may optionally have a ’=’ operator within them to specify a definition value. Those without an ’=’ will implicitly have a definition of 1. For example\+:


\begin{DoxyCode}
\textcolor{comment}{// in your GLSL}

\textcolor{preprocessor}{#ifdef CLEVERTECHNIQUE}
    \textcolor{comment}{// some clever stuff here}
\textcolor{preprocessor}{#else}
    \textcolor{comment}{// normal technique}
\textcolor{preprocessor}{#endif}

\textcolor{preprocessor}{#if NUM\_THINGS==2}
    \textcolor{comment}{// Some specific code}
\textcolor{preprocessor}{#else}
    \textcolor{comment}{// something else}
\textcolor{preprocessor}{#endif}

\textcolor{comment}{// in  your program definition}
preprocessor\_defines CLEVERTECHNIQUE,NUMTHINGS=2
\end{DoxyCode}


This way you can use the same source code but still include small variations, each one defined as a different \hyperlink{namespace_ogre}{Ogre} program name but based on the same source code.\hypertarget{_high-level-_programs_GLSL-Geometry-shader-specification}{}\subsubsection{G\+L\+S\+L Geometry shader specification}\label{_high-level-_programs_GLSL-Geometry-shader-specification}
G\+L\+SL allows the same shader to run on different types of geometry primitives. In order to properly link the shaders together, you have to specify which primitives it will receive as input, which primitives it will emit and how many vertices a single run of the shader can generate. The G\+L\+SL geometry\+\_\+program definition requires three additional parameters \+:


\begin{DoxyDescription}
\item[input\+\_\+operation\+\_\+type ]

The operation type of the geometry that the shader will receive. Can be ’point\+\_\+list’, ’line\+\_\+list’, ’line\+\_\+strip’, ’triangle\+\_\+list’, ’triangle\+\_\+strip’ or ’triangle\+\_\+fan’.


\item[output\+\_\+operation\+\_\+type ]

The operation type of the geometry that the shader will emit. Can be ’point\+\_\+list’, ’line\+\_\+strip’ or ’triangle\+\_\+strip’.


\item[max\+\_\+output\+\_\+vertices ]

The maximum number of vertices that the shader can emit. There is an upper limit for this value, it is exposed in the render system capabilities.


\end{DoxyDescription}

For example\+:


\begin{DoxyCode}
geometry\_program \hyperlink{namespace_ogre}{Ogre}/GPTest/Swizzle\_GP\_GLSL glsl
\{
    source SwizzleGP.glsl
    input\_operation\_type triangle\_list
    output\_operation\_type line\_strip
    max\_output\_vertices 6
\}
\end{DoxyCode}
\hypertarget{_high-level-_programs_Unified-High_002dlevel-Programs}{}\subsection{Unified High-\/level Programs}\label{_high-level-_programs_Unified-High_002dlevel-Programs}
As mentioned above, it can often be useful to write both H\+L\+SL and G\+L\+SL programs to specifically target each platform, but if you do this via multiple material techniques this can cause a bloated material definition when the only difference is the program language. Well, there is another option. You can ’wrap’ multiple programs in a ’unified’ program definition, which will automatically choose one of a series of ’delegate’ programs depending on the rendersystem and hardware support.


\begin{DoxyCode}
vertex\_program myVertexProgram unified
\{
    delegate realProgram1
    delegate realProgram2
    ... etc
\}
\end{DoxyCode}


This works for both vertex and fragment programs, and you can list as many delegates as you like -\/ the first one to be supported by the current rendersystem \& hardware will be used as the real program. This is almost like a mini-\/technique system, but for a single program and with a much tighter purpose. You can only use this where the programs take all the same inputs, particularly textures and other pass / sampler state. Where the only difference between the programs is the language (or possibly the target in H\+L\+SL -\/ you can include multiple H\+L\+SL programs with different targets in a single unified program too if you want, or indeed any number of other high-\/level programs), this can become a very powerful feature. For example, without this feature here’s how you’d have to define a programmable material which supported H\+L\+SL and G\+L\+SL\+:


\begin{DoxyCode}
vertex\_program myVertexProgramHLSL hlsl
\{
    source prog.hlsl
    entry\_point main\_vp
    target vs\_2\_0
\}
fragment\_program myFragmentProgramHLSL hlsl
\{
    source prog.hlsl
    entry\_point main\_fp
    target ps\_2\_0
\}
vertex\_program myVertexProgramGLSL glsl
\{
    source prog.vert
\}
fragment\_program myFragmentProgramGLSL glsl
\{
    source prog.frag
    default\_params
    \{
        param\_named tex \textcolor{keywordtype}{int} 0
    \}
\}
material SupportHLSLandGLSLwithoutUnified
\{
    \textcolor{comment}{// HLSL technique}
    technique
    \{
        pass
        \{
            vertex\_program\_ref myVertexProgramHLSL
            \{
                param\_named\_auto worldViewProj world\_view\_proj\_matrix
                param\_named\_auto lightColour light\_diffuse\_colour 0
                param\_named\_auto lightSpecular light\_specular\_colour 0
                param\_named\_auto lightAtten light\_attenuation 0
            \}
            fragment\_program\_ref myFragmentProgramHLSL
            \{
            \}
        \}
    \}
    \textcolor{comment}{// GLSL technique}
    technique
    \{
        pass
        \{
            vertex\_program\_ref myVertexProgramHLSL
            \{
                param\_named\_auto worldViewProj world\_view\_proj\_matrix
                param\_named\_auto lightColour light\_diffuse\_colour 0
                param\_named\_auto lightSpecular light\_specular\_colour 0
                param\_named\_auto lightAtten light\_attenuation 0
            \}
            fragment\_program\_ref myFragmentProgramHLSL
            \{
            \}
        \}
    \}
\}
\end{DoxyCode}


And that’s a really small example. Everything you added to the H\+L\+SL technique, you’d have to duplicate in the G\+L\+SL technique too. So instead, here’s how you’d do it with unified program definitions\+:


\begin{DoxyCode}
vertex\_program myVertexProgramHLSL hlsl
\{
    source prog.hlsl
    entry\_point main\_vp
    target vs\_2\_0
\}
fragment\_program myFragmentProgramHLSL hlsl
\{
    source prog.hlsl
    entry\_point main\_fp
    target ps\_2\_0
\}
vertex\_program myVertexProgramGLSL glsl
\{
    source prog.vert
\}
fragment\_program myFragmentProgramGLSL glsl
\{
    source prog.frag
    default\_params
    \{
        param\_named tex \textcolor{keywordtype}{int} 0
    \}
\}
\textcolor{comment}{// Unified definition}
vertex\_program myVertexProgram unified
\{
    delegate myVertexProgramGLSL
    delegate myVertexProgramHLSL
\}
fragment\_program myFragmentProgram unified
\{
    delegate myFragmentProgramGLSL
    delegate myFragmentProgramHLSL
\}
material SupportHLSLandGLSLwithUnified
\{
    \textcolor{comment}{// HLSL technique}
    technique
    \{
        pass
        \{
            vertex\_program\_ref myVertexProgram
            \{
                param\_named\_auto worldViewProj world\_view\_proj\_matrix
                param\_named\_auto lightColour light\_diffuse\_colour 0
                param\_named\_auto lightSpecular light\_specular\_colour 0
                param\_named\_auto lightAtten light\_attenuation 0
            \}
            fragment\_program\_ref myFragmentProgram
            \{
            \}
        \}
    \}
\}
\end{DoxyCode}


At runtime, when my\+Vertex\+Program or my\+Fragment\+Program are used, O\+G\+RE automatically picks a real program to delegate to based on what’s supported on the current hardware / rendersystem. If none of the delegates are supported, the entire technique referencing the unified program is marked as unsupported and the next technique in the material is checked fro fallback, just like normal. As your materials get larger, and you find you need to support H\+L\+SL and G\+L\+SL specifically (or need to write multiple interface-\/compatible versions of a program for whatever other reason), unified programs can really help reduce duplication.\hypertarget{_high-level-_programs_Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass}{}\subsection{Using G\+P\+U Programs in a Pass}\label{_high-level-_programs_Using-Vertex_002fGeometry_002fFragment-Programs-in-a-Pass}
Within a pass section of a material script, you can reference a vertex, geometry and / or a fragment program which is been defined in a .program script (See \hyperlink{_material-_scripts_Declaring-Vertex_002fGeometry_002fFragment-Programs}{Declaring G\+PU Programs}). The programs are defined separately from the usage of them in the pass, since the programs are very likely to be reused between many separate materials, probably across many different .material scripts, so this approach lets you define the program only once and use it many times.

As well as naming the program in question, you can also provide parameters to it. Here’s a simple example\+:


\begin{DoxyCode}
vertex\_program\_ref myVertexProgram
\{
    param\_indexed\_auto 0 worldviewproj\_matrix
    param\_indexed      4 float4  10.0 0 0 0
\}
\end{DoxyCode}


In this example, we bind a vertex program called ’my\+Vertex\+Program’ (which will be defined elsewhere) to the pass, and give it 2 parameters, one is an ’auto’ parameter, meaning we do not have to supply a value as such, just a recognised code (in this case it’s the world/view/projection matrix which is kept up to date automatically by \hyperlink{namespace_ogre}{Ogre}). The second parameter is a manually specified parameter, a 4-\/element float. The indexes are described later.

The syntax of the link to a vertex program and a fragment or geometry program are identical, the only difference is that ’fragment\+\_\+program\+\_\+ref’ and ’geometry\+\_\+program\+\_\+ref’ are used respectively instead of ’vertex\+\_\+program\+\_\+ref’.

For many situations vertex, geometry and fragment programs are associated with each other in a pass but this is not cast in stone. You could have a vertex program that can be used by several different fragment programs. Another situation that arises is that you can mix fixed pipeline and programmable pipeline (shaders) together. You could use the non-\/programmable vertex fixed function pipeline and then provide a fragment\+\_\+program\+\_\+ref in a pass i.\+e. there would be no vertex\+\_\+program\+\_\+ref section in the pass. The fragment program referenced in the pass must meet the requirements as defined in the related A\+PI in order to read from the outputs of the vertex fixed pipeline. You could also just have a vertex program that outputs to the fragment fixed function pipeline.

The requirements to read from or write to the fixed function pipeline are similar between rendering A\+P\+I’s (DirectX and Open\+GL) but how its actually done in each type of shader (vertex, geometry or fragment) depends on the shader language. For H\+L\+SL (DirectX A\+PI) and associated asm consult M\+S\+DN at \href{http://msdn.microsoft.com/library/}{\tt http\+://msdn.\+microsoft.\+com/library/}. For G\+L\+SL (Open\+GL), consult section 7.\+6 of the G\+L\+SL spec 1.\+1 available at \href{http://www.opengl.org/registry/}{\tt http\+://www.\+opengl.\+org/registry/}. The built in varying variables provided in G\+L\+SL allow your program to read/write to the fixed function pipeline varyings. For Cg consult the Language Profiles section in Cg\+Users\+Manual.\+pdf that comes with the Cg Toolkit available at \href{https://developer.nvidia.com/cg-toolkit}{\tt https\+://developer.\+nvidia.\+com/cg-\/toolkit}. For H\+L\+SL and Cg its the varying bindings that allow your shader programs to read/write to the fixed function pipeline varyings.\hypertarget{_high-level-_programs_Program-Parameter-Specification}{}\subsubsection{Parameter specification}\label{_high-level-_programs_Program-Parameter-Specification}
Parameters can be specified using one of 4 commands as shown below. The same syntax is used whether you are defining a parameter just for this particular use of the program, or when specifying the \hyperlink{_material-_scripts_Default-Program-Parameters}{Default Program Parameters}. Parameters set in the specific use of the program override the defaults.


\begin{DoxyItemize}
\item \href{#param_005findexed}{\tt param\+\_\+indexed}
\item \href{#param_005findexed_005fauto}{\tt param\+\_\+indexed\+\_\+auto}
\item \href{#param_005fnamed}{\tt param\+\_\+named}
\item \href{#param_005fnamed_005fauto}{\tt param\+\_\+named\+\_\+auto}
\item \href{#shared_005fparams_005fref}{\tt shared\+\_\+params\+\_\+ref}
\end{DoxyItemize}

\label{_param_005findexed}%
\label{_param_005findexed-1}%


\subsection*{param\+\_\+indexed}

This command sets the value of an indexed parameter.

format\+: param\+\_\+indexed $<$index$>$ $<$type$>$ $<$value$>$ example\+: param\+\_\+indexed 0 float4 10.\+0 0 0 0


\begin{DoxyParams}{Parameters}
{\em index} & simply a number representing the position in the parameter list which the value should be written, and you should derive this from your program definition. The index is relative to the way constants are stored on the card, which is in 4-\/element blocks. For example if you defined a float4 parameter at index 0, the next index would be 1. If you defined a matrix4x4 at index 0, the next usable index would be 4, since a 4x4 matrix takes up 4 indexes.\\
\hline
{\em type} & can be float4, matrix4x4, float$<$n$>$, int4, int$<$n$>$. Note that ’int’ parameters are only available on some more advanced program syntaxes, check the D3D or GL vertex / fragment program documentation for full details. Typically the most useful ones will be float4 and matrix4x4. Note that if you use a type which is not a multiple of 4, then the remaining values up to the multiple of 4 will be filled with zeroes for you (since G\+P\+Us always use banks of 4 floats per constant even if only one is used).\\
\hline
{\em value} & a space or tab-\/delimited list of values which can be converted into the type you have specified.\\
\hline
\end{DoxyParams}
\label{_param_005findexed_005fauto}%
\label{_param_005findexed_005fauto-1}%


\subsection*{param\+\_\+indexed\+\_\+auto}

This command tells \hyperlink{namespace_ogre}{Ogre} to automatically update a given parameter with a derived value. This frees you from writing code to update program parameters every frame when they are always changing.

format\+: param\+\_\+indexed\+\_\+auto $<$index$>$ $<$value\+\_\+code$>$ $<$extra\+\_\+params$>$ example\+: param\+\_\+indexed\+\_\+auto 0 worldviewproj\+\_\+matrix


\begin{DoxyParams}{Parameters}
{\em index} & has the same meaning as \href{#param_005findexed}{\tt param\+\_\+indexed}; note this time you do not have to specify the size of the parameter because the engine knows this already. In the example, the world/view/projection matrix is being used so this is implicitly a matrix4x4.\\
\hline
{\em value\+\_\+code} & is one of \hyperlink{class_ogre_1_1_gpu_program_parameters_a155c886f15e0c10d2c33c224f0d43ce3}{Ogre\+::\+Gpu\+Program\+Parameters\+::\+Auto\+Constant\+Type} without the {\ttfamily A\+C\+T\+\_\+} prefix. E.\+g. {\ttfamily A\+C\+T\+\_\+\+W\+O\+R\+L\+D\+\_\+\+M\+A\+T\+R\+IX} becomes {\ttfamily world\+\_\+matrix}.\\
\hline
\end{DoxyParams}
\label{_param_005fnamed}%
\label{_param_005fnamed-1}%


\subsection*{param\+\_\+named}

This is the same as param\+\_\+indexed, but uses a named parameter instead of an index. This can only be used with high-\/level programs which include parameter names; if you’re using an assembler program then you have no choice but to use indexes. Note that you can use indexed parameters for high-\/level programs too, but it is less portable since if you reorder your parameters in the high-\/level program the indexes will change. format\+: param\+\_\+named $<$name$>$ $<$type$>$ $<$value$>$ example\+: param\+\_\+named shininess float4 10.\+0 0 0 0 The type is required because the program is not compiled and loaded when the material script is parsed, so at this stage we have no idea what types the parameters are. Programs are only loaded and compiled when they are used, to save memory.

\label{_param_005fnamed_005fauto}%
\label{_param_005fnamed_005fauto-1}%


\subsection*{param\+\_\+named\+\_\+auto}

This is the named equivalent of param\+\_\+indexed\+\_\+auto, for use with high-\/level programs. Format\+: param\+\_\+named\+\_\+auto $<$name$>$ $<$value\+\_\+code$>$ $<$extra\+\_\+params$>$ Example\+: param\+\_\+named\+\_\+auto world\+View\+Proj W\+O\+R\+L\+D\+V\+I\+E\+W\+P\+R\+O\+J\+\_\+\+M\+A\+T\+R\+IX

The allowed value codes and the meaning of extra\+\_\+params are detailed in \href{#param_005findexed_005fauto}{\tt param\+\_\+indexed\+\_\+auto}.

\label{_shared_005fparams_005fref}%
\label{_shared_005fparams_005fref-1}%


\subsection*{shared\+\_\+params\+\_\+ref}

This option allows you to reference shared parameter sets as defined in \hyperlink{_material-_scripts_Declaring-Shared-Parameters}{Declaring Shared Parameters}. \begin{DoxyParagraph}{}
Format\+: shared\+\_\+params\+\_\+ref $<$shared\+\_\+set\+\_\+name$>$ 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: shared\+\_\+params\+\_\+ref my\+Shared\+Params
\end{DoxyParagraph}
The only required parameter is a name, which must be the name of an already defined shared parameter set. All named parameters which are present in the program that are also present in the shared parameter set will be linked, and the shared parameters used as if you had defined them locally. This is dependent on the definitions (type and array size) matching between the shared set and the program.\hypertarget{_high-level-_programs_Shadows-and-Vertex-Programs}{}\subsection{Shadows and Vertex Programs}\label{_high-level-_programs_Shadows-and-Vertex-Programs}
When using shadows (See \hyperlink{Shadows}{Shadows}), the use of vertex programs can add some additional complexities, because \hyperlink{namespace_ogre}{Ogre} can only automatically deal with everything when using the fixed-\/function pipeline. If you use vertex programs, and you are also using shadows, you may need to make some adjustments.

If you use {\bfseries stencil shadows}, then any vertex programs which do vertex deformation can be a problem, because stencil shadows are calculated on the C\+PU, which does not have access to the modified vertices. If the vertex program is doing standard skeletal animation, this is ok (see section above) because \hyperlink{namespace_ogre}{Ogre} knows how to replicate the effect in software, but any other vertex deformation cannot be replicated, and you will either have to accept that the shadow will not reflect this deformation, or you should turn off shadows for that object.

If you use {\bfseries texture shadows}, then vertex deformation is acceptable; however, when rendering the object into the shadow texture (the shadow caster pass), the shadow has to be rendered in a solid colour (linked to the ambient colour). You must therefore provide an alternative vertex program, so \hyperlink{namespace_ogre}{Ogre} provides you with a way of specifying one to use when rendering the caster. Basically you link an alternative vertex program, using exactly the same syntax as the original vertex program link\+:


\begin{DoxyCode}
shadow\_caster\_vertex\_program\_ref myShadowCasterVertexProgram
\{
    param\_indexed\_auto 0 worldviewproj\_matrix
    param\_indexed\_auto 4 ambient\_light\_colour
\}
\end{DoxyCode}


When rendering a shadow caster, \hyperlink{namespace_ogre}{Ogre} will automatically use the alternate program. You can bind the same or different parameters to the program -\/ the most important thing is that you bind {\bfseries ambient\+\_\+light\+\_\+colour}, since this determines the colour of the shadow in modulative texture shadows. If you don’t supply an alternate program, \hyperlink{namespace_ogre}{Ogre} will fall back on a fixed-\/function material which will not reflect any vertex deformation you do in your vertex program.

In addition, when rendering the shadow receivers with shadow textures, \hyperlink{namespace_ogre}{Ogre} needs to project the shadow texture. It does this automatically in fixed function mode, but if the receivers use vertex programs, they need to have a shadow receiver program which does the usual vertex deformation, but also generates projective texture coordinates. The additional program linked into the pass like this\+:


\begin{DoxyCode}
shadow\_receiver\_vertex\_program\_ref myShadowReceiverVertexProgram
\{
    param\_indexed\_auto 0 worldviewproj\_matrix
    param\_indexed\_auto 4 texture\_viewproj\_matrix
\}
\end{DoxyCode}


For the purposes of writing this alternate program, there is an automatic parameter binding of ’texture\+\_\+viewproj\+\_\+matrix’ which provides the program with texture projection parameters. The vertex program should do it’s normal vertex processing, and generate texture coordinates using this matrix and place them in texture coord sets 0 and 1, since some shadow techniques use 2 texture units. The colour of the vertices output by this vertex program must always be white, so as not to affect the final colour of the rendered shadow.

When using additive texture shadows, the shadow pass render is actually the lighting render, so if you perform any fragment program lighting you also need to pull in a custom fragment program. You use the shadow\+\_\+receiver\+\_\+fragment\+\_\+program\+\_\+ref for this\+:


\begin{DoxyCode}
shadow\_receiver\_fragment\_program\_ref myShadowReceiverFragmentProgram
\{
    param\_named\_auto lightDiffuse light\_diffuse\_colour 0 
\}
\end{DoxyCode}


You should pass the projected shadow coordinates from the custom vertex program. As for textures, texture unit 0 will always be the shadow texture. Any other textures which you bind in your pass will be carried across too, but will be moved up by 1 unit to make room for the shadow texture. Therefore your shadow receiver fragment program is likely to be the same as the bare lighting pass of your normal material, except that you insert an extra texture sampler at index 0, which you will use to adjust the result by (modulating diffuse and specular components).\hypertarget{_high-level-_programs_Skeletal-Animation-in-Vertex-Programs}{}\subsection{Skeletal Animation in Vertex Programs}\label{_high-level-_programs_Skeletal-Animation-in-Vertex-Programs}
You can implement skeletal animation in hardware by writing a vertex program which uses the per-\/vertex blending indices and blending weights, together with an array of world matrices (which will be provided for you by \hyperlink{namespace_ogre}{Ogre} if you bind the automatic parameter ’world\+\_\+matrix\+\_\+array\+\_\+3x4’). However, you need to communicate this support to \hyperlink{namespace_ogre}{Ogre} so it does not perform skeletal animation in software for you. You do this by adding the following attribute to your vertex\+\_\+program definition\+:


\begin{DoxyCode}
includes\_skeletal\_animation \textcolor{keyword}{true}
\end{DoxyCode}


When you do this, any skeletally animated entity which uses this material will forgo the usual animation blend and will expect the vertex program to do it, for both vertex positions and normals. Note that A\+LL submeshes must be assigned a material which implements this, and that if you combine skeletal animation with vertex animation (See \hyperlink{Animation}{Animation}) then all techniques must be hardware accelerated for any to be.\hypertarget{_high-level-_programs_Morph-Animation-in-Vertex-Programs}{}\subsection{Morph Animation in Vertex Programs}\label{_high-level-_programs_Morph-Animation-in-Vertex-Programs}
You can implement morph animation in hardware by writing a vertex program which linearly blends between the first and second position keyframes passed as positions and the first free texture coordinate set, and by binding the animation\+\_\+parametric value to a parameter (which tells you how far to interpolate between the two). However, you need to communicate this support to \hyperlink{namespace_ogre}{Ogre} so it does not perform morph animation in software for you. You do this by adding the following attribute to your vertex\+\_\+program definition\+:


\begin{DoxyCode}
includes\_morph\_animation \textcolor{keyword}{true}
\end{DoxyCode}


When you do this, any skeletally animated entity which uses this material will forgo the usual software morph and will expect the vertex program to do it. Note that if your model includes both skeletal animation and morph animation, they must both be implemented in the vertex program if either is to be hardware acceleration. Note that A\+LL submeshes must be assigned a material which implements this, and that if you combine skeletal animation with vertex animation (See \href{#Animation}{\tt Animation}) then all techniques must be hardware accelerated for any to be.\hypertarget{_high-level-_programs_Pose-Animation-in-Vertex-Programs}{}\subsection{Pose Animation in Vertex Programs}\label{_high-level-_programs_Pose-Animation-in-Vertex-Programs}
You can implement pose animation (blending between multiple poses based on weight) in a vertex program by pulling in the original vertex data (bound to position), and as many pose offset buffers as you’ve defined in your ’includes\+\_\+pose\+\_\+animation’ declaration, which will be in the first free texture unit upwards. You must also use the animation\+\_\+parametric parameter to define the starting point of the constants which will contain the pose weights; they will start at the parameter you define and fill ’n’ constants, where ’n’ is the max number of poses this shader can blend, i.\+e. the parameter to includes\+\_\+pose\+\_\+animation.


\begin{DoxyCode}
includes\_pose\_animation 4
\end{DoxyCode}


Note that A\+LL submeshes must be assigned a material which implements this, and that if you combine skeletal animation with vertex animation (See \href{#Animation}{\tt Animation}) then all techniques must be hardware accelerated for any to be.\hypertarget{_high-level-_programs_Vertex-texture-fetching-in-vertex-programs}{}\subsection{Vertex texture fetching in vertex programs}\label{_high-level-_programs_Vertex-texture-fetching-in-vertex-programs}
If your vertex program makes use of \href{#Vertex-Texture-Fetch}{\tt Vertex Texture Fetch}, you should declare that with the ’uses\+\_\+vertex\+\_\+texture\+\_\+fetch’ directive. This is enough to tell \hyperlink{namespace_ogre}{Ogre} that your program uses this feature and that hardware support for it should be checked.


\begin{DoxyCode}
uses\_vertex\_texture\_fetch \textcolor{keyword}{true}
\end{DoxyCode}
\hypertarget{_high-level-_programs_Vertex-Texture-Fetch}{}\subsection{Vertex Texture Fetch}\label{_high-level-_programs_Vertex-Texture-Fetch}
More recent generations of video card allow you to perform a read from a texture in the vertex program rather than just the fragment program, as is traditional. This allows you to, for example, read the contents of a texture and displace vertices based on the intensity of the colour contained within.

\label{_Declaring-the-use-of-vertex-texture-fetching}%


\subsection*{Declaring the use of vertex texture fetching}

Since hardware support for vertex texture fetching is not ubiquitous, you should use the uses\+\_\+vertex\+\_\+texture\+\_\+fetch (See \href{#Vertex-texture-fetching-in-vertex-programs}{\tt Vertex texture fetching in vertex programs}) directive when declaring your vertex programs which use vertex textures, so that if it is not supported, technique fallback can be enabled. This is not strictly necessary for Direct\+X-\/targeted shaders, since vertex texture fetching is only supported in vs\+\_\+3\+\_\+0, which can be stated as a required syntax in your shader definition, but for Open\+GL (G\+L\+SL), there are cards which support G\+L\+SL but not vertex textures, so you should be explicit about your need for them.

\label{_Render-system-texture-binding-differences}%


\subsection*{Render system texture binding differences}

Unfortunately the method for binding textures so that they are available to a vertex program is not well standardised. As at the time of writing, Shader Model 3.\+0 (S\+M3.\+0) hardware under Direct\+X9 include 4 separate sampler bindings for the purposes of vertex textures. Open\+GL, on the other hand, is able to access vertex textures in G\+L\+SL (and in assembler through N\+V\+\_\+vertex\+\_\+program\+\_\+3, although this is less popular), but the textures are shared with the fragment pipeline. I expect DirectX to move to the GL model with the advent of Direct\+X10, since a unified shader architecture implies sharing of texture resources between the two stages. As it is right now though, we’re stuck with an inconsistent situation.

To reflect this, you should use the \href{#binding_005ftype}{\tt binding\+\_\+type} attribute in a texture unit to indicate which unit you are targeting with your texture -\/ ’fragment’ (the default) or ’vertex’. For render systems that don’t have separate bindings, this actually does nothing. But for those that do, it will ensure your texture gets bound to the right processing unit.

Note that whilst Direct\+X9 has separate bindings for the vertex and fragment pipelines, binding a texture to the vertex processing unit still uses up a ’slot’ which is then not available for use in the fragment pipeline. I didn’t manage to find this documented anywhere, but the n\+Vidia samples certainly avoid binding a texture to the same index on both vertex and fragment units, and when I tried to do it, the texture did not appear correctly in the fragment unit, whilst it did as soon as I moved it into the next unit.

\label{_Texture-format-limitations}%


\subsection*{Texture format limitations}

Again as at the time of writing, the types of texture you can use in a vertex program are limited to 1-\/ or 4-\/component, full precision floating point formats. In code that equates to P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+R or P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+\+R\+G\+BA. No other formats are supported. In addition, the textures must be regular 2D textures (no cube or volume maps) and mipmapping and filtering is not supported, although you can perform filtering in your vertex program if you wish by sampling multiple times.

\label{_Hardware-limitations}%


\subsection*{Hardware limitations}

As at the time of writing (early Q3 2006), A\+TI do not support texture fetch in their current crop of cards (Radeon X1n00). n\+Vidia do support it in both their 6n00 and 7n00 range. A\+TI support an alternative called ’\+Render to Vertex Buffer’, but this is not standardised at this time and is very much different in its implementation, so cannot be considered to be a drop-\/in replacement. This is the case even though the Radeon X1n00 cards claim to support vs\+\_\+3\+\_\+0 (which requires vertex texture fetch). \hypertarget{Runtime-Shader-Generation}{}\section{Runtime Shader Generation}\label{Runtime-Shader-Generation}
Writing shading programs is a common task when developing 3D based application. Most of the visual effects used by 3D based applications involve shader programs. Additionally with D3\+D11, support for fixed pipeline functionality was removed. Meaning you can only render objects using shaders.

While \hyperlink{High-level-Programs}{High-\/level Programs} offer you maximal control and flexibility over how your objects are rendered, writing and maintaining them is also a very time consuming task.

Instead Ogre can also automatically generate shaders on the fly, based on object material properties, scene setup and other user definitions. While the resulting shaders are less optimized, they offer the following advantages\+:


\begin{DoxyItemize}
\item Save development time e.\+g. when your target scene has dynamic lights and the number changes, fog changes and the number of material attributes increases the total count of needed shaders dramatically. It can easily cross 100 and it becomes a time consuming development task.
\item Reusable code -\/ once you\textquotesingle{}ve written the shader extension you can use it anywhere due to its independent nature.
\item Custom shaders extension library -\/ enjoy the shared library of effects created by the community. Unlike hand written shader code, which may require many adjustments to be plugged into your own shader code, using the extensions library requires minimum changes.
\end{DoxyItemize}

You have the choice between two different systems, which are implemented as components. You can select the one you need (or disable both) at compile time.


\begin{DoxyItemize}
\item \hyperlink{rtss}{R\+T\+S\+S\+: Run Time Shader System} ~\newline
 The R\+T\+SS is not another Uber shader with an exploding amount of {\ttfamily \#ifdefs} that make it increasingly difficult to add new functionality. Instead, it manages a set of opaque isolated components (Sub\+Render\+States) where each implements a specific effect. These \char`\"{}effects\char`\"{} notable include full Fixed Function emulation. At the core these components are plain shader files providing a set of functions. The shaders are based on properties defined in \hyperlink{Material-Scripts}{Material Scripts}.
\item \hyperlink{hlms}{H\+L\+M\+S\+: High Level Material System} ~\newline
 This component allows you to manage shader variations of a specific shader template. This is a different take to the Uber shader management, but instead of using plain {\ttfamily \#ifdefs} it uses a custom, more powerful preprocessor language. Currently the H\+L\+MS can be only configured via a custom A\+PI and does not respect classical \hyperlink{class_ogre_1_1_material}{Ogre\+::\+Material} properties.
\end{DoxyItemize}

\section*{Historical background}

When the early graphic cards came into the market they contained a fixed but large set of functions with which you could influence how 3D object were rendered. These included influencing object positions using matrices, calculating the effect of textures on a pixel, calculating the effect of lights on vertices and so on. These set of functions and their implementation in hardware became later known as the graphic card fixed pipeline (or Fixed Function Pipeline).

As graphic cards became more powerful and graphic application became more complex, a need for new ways to manipulate the rendering of 3D models became apparent. This need saw the introduction of shaders.

Shaders are small custom made programs that run directly on the graphics card. Using these programs, one could replace the calculations that were made by the fixed pipeline and add new functionality. However there was a catch\+: If shaders are used on an object, the object can no longer use any of the functionality of the fixed pipeline. Any calculation that was used in the fixed pipeline needed to be recreated in the shaders. With early graphics applications this was not problematic. Shaders were simple and their numbers were kept low. However as applications grew in complexity this meant that the need for shaders grew as well. As a programmer you were left with 2 choices, both bad. Either create an exuberant amount of small shaders that soon became too many to effectively maintain. Or create an uber shader, a huge complex shader, that soon became too complex to effectively maintain as well.

The R\+T\+SS seeks to fix those problems by automatically generating shaders based on the operations previously required from the fixed pipeline and new capabilities required by the user.

With the introduction of the version 11 of Direct3D, a new reason for having an R\+T\+SS like system became apparent. With D3\+D11 support for fixed pipeline functionality was removed. Meaning, you can only render objects using shaders. The R\+T\+SS is an excellent tool for this purpose. \hypertarget{rtss}{}\subsection{R\+T\+SS\+: Run Time Shader System}\label{rtss}
\hypertarget{rtss_core-feats}{}\subsubsection{Core features of the system}\label{rtss_core-feats}

\begin{DoxyItemize}
\item Runtime shader generation synchronized with scene state. Each time scene settings change, a new set of shaders is generated.
\item Full Fixed Function Pipeline (F\+FP) emulation. This feature is most useful combined with render system that doesn\textquotesingle{}t provide any F\+FP functionality (Open\+GL ES 2.\+0, D3\+D11 etc).
\item Shader language independent interface\+: the logic representation of the shader programs is completely independent from the target shader language. You can generate code for different shader languages from the same program.
\item Pluggable interface allows extending the target shader languages set.
\item Pluggable interface allows adding new shader based effects to the system in a seamless way. Each effect code will be automatically combined with the rest of the shader code.
\item Smart program management\+: each shader program is created only once and may be used by multiple passes.
\item Automatic vertex shader compacting mechanism\+: no more compacting variables by hand. In case the amount of used vertex shader output registers exceeds the maximum allowed (12 to 32, depending on \href{http://msdn.microsoft.com/en-us/library/bb172918%28v=VS.85%29.aspx}{\tt D3\+D\+P\+S\+H\+A\+D\+E\+R\+C\+A\+P\+S2\+\_\+0.\+Num\+Temps}), a compacting algorithm packs the vertex shader outputs and adds unpack code in the fragment shader side.
\item Material script support, for both export and import.
\end{DoxyItemize}\hypertarget{rtss_rtss_overview}{}\subsubsection{System overview}\label{rtss_rtss_overview}
The R\+T\+SS manages a set of opaque isolated components (Sub\+Render\+States) where each implements a specific effect. These \char`\"{}effects\char`\"{} include Fixed Function transformation and lighting. At the core these components are plain shader files providing a set of functions; e.\+g. \hyperlink{group___r_t_shader_ga64839e79eb9f1102d5ba2f9a8de44529}{F\+F\+P\+\_\+\+F\+U\+N\+C\+\_\+\+L\+I\+G\+H\+T\+\_\+\+D\+I\+R\+E\+C\+T\+I\+O\+N\+A\+L\+\_\+\+D\+I\+F\+F\+U\+SE}, \hyperlink{group___r_t_shader_gae018fb3c504d2c78a7ae5df29613b369}{F\+F\+P\+\_\+\+F\+U\+N\+C\+\_\+\+L\+I\+G\+H\+T\+\_\+\+P\+O\+I\+N\+T\+\_\+\+D\+I\+F\+F\+U\+SE}.

Correctly ordering these functions, providing them with the right input values and interconnecting them is the main purpose of the R\+T\+SS.

To this end the R\+T\+SS defines a set of stages; e.\+g \hyperlink{group___r_t_shader_gga4c92eba13eb8038d35530610c58ceff4a89872e19110c14f19fa11bd6c04755c4}{Ogre\+::\+R\+T\+Shader\+::\+F\+F\+P\+\_\+\+T\+R\+A\+N\+S\+F\+O\+RM}, \hyperlink{group___r_t_shader_gga4c92eba13eb8038d35530610c58ceff4a4633e1da9bc8ecbdecf34cd5cc4918d0}{Ogre\+::\+R\+T\+Shader\+::\+F\+F\+P\+\_\+\+T\+E\+X\+T\+U\+R\+I\+NG}. It then queries all registered Sub\+Render\+States which in turn attach functions given a \hyperlink{class_ogre_1_1_pass}{Ogre\+::\+Pass}. The stages are conceptually very similar to render queue groups.

After the R\+T\+SS has queried the Sub\+Render\+States it continues to fill the entry function (e.\+g. {\ttfamily main()} for G\+L\+SL) by generating the actual function invocations.

Basically it performs the following (simplified) transformation, given 
\begin{DoxyCode}
\textcolor{comment}{// GLOBAL PARAMETERS}
$global\_parameters
\textcolor{comment}{// FUNCTION}
$input\_parameters
$output\_parameters
\textcolor{keywordtype}{void} main() \{
    $local\_parameters
    $FFP\_VS\_TRANSFORM
    (...)
    $FFP\_VS\_TEXTURING
\}
\end{DoxyCode}
 and {\ttfamily \$\+F\+F\+P\+\_\+\+V\+S\+\_\+\+T\+R\+A\+N\+S\+F\+O\+RM = \mbox{[}F\+F\+P\+\_\+\+F\+U\+N\+C\+\_\+\+T\+R\+A\+N\+S\+F\+O\+RM\mbox{]}}, {\ttfamily \$\+F\+F\+P\+\_\+\+V\+S\+\_\+\+T\+E\+X\+T\+U\+R\+I\+NG = \mbox{[}F\+F\+P\+\_\+\+F\+U\+N\+C\+\_\+\+T\+R\+A\+N\+S\+F\+O\+R\+M\+\_\+\+T\+E\+X\+C\+O\+O\+RD\mbox{]}}, it generates


\begin{DoxyCode}
\textcolor{comment}{// GLOBAL PARAMETERS}
uniform mat4    worldviewproj\_matrix;
uniform mat4    texture\_matrix1;
\textcolor{comment}{// FUNCTION}
in  vec4    vertex;
in  vec4    uv0;
out vec4    oTexcoord4\_0;
\textcolor{keywordtype}{void} main() \{
    FFP\_Transform(worldviewproj\_matrix, vertex, gl\_Position);
    FFP\_TransformTexCoord(texture\_matrix1, uv0.xy, oTexcoord4\_0.xy);
\}
\end{DoxyCode}


It will automatically use \hyperlink{class_ogre_1_1_gpu_program_parameters_a155c886f15e0c10d2c33c224f0d43ce3}{Ogre\+::\+Gpu\+Program\+Parameters\+::\+Auto\+Constant\+Type} as needed to obtain the required inputs and route them in the respective functions. In the above example no local parameters were allocated, but the R\+T\+SS will do it as needed. (for instance if you try to write to \char`\"{}vertex\char`\"{} in G\+L\+SL)

Now that you know what the R\+T\+SS does, you are probably wondering how to change which functions are emitted per stage to, lets say, change the lighting from the F\+FP style per-\/vertex lighting to per-\/pixel lighting.

The R\+T\+SS is flexible enough to \char`\"{}just\char`\"{} move the according calculations from the vertex shader to the pixel shader.\hypertarget{rtss_rtss_custom_api}{}\paragraph{Customising the R\+T\+S\+S using the A\+PI}\label{rtss_rtss_custom_api}
The first option is to globally enforce per-\/pixel lighting, you can do the following


\begin{DoxyCodeInclude}
        \textcolor{comment}{// Grab the scheme render state.}
        \hyperlink{class_ogre_1_1_r_t_shader_1_1_render_state}{Ogre::RTShader::RenderState}* schemRenderState =
            mShaderGenerator->getRenderState(
      \hyperlink{class_ogre_1_1_r_t_shader_1_1_shader_generator_a50a41bdc60047796354703d8d77d028a}{Ogre::RTShader::ShaderGenerator::DEFAULT\_SCHEME\_NAME});

        \textcolor{comment}{// Add per pixel lighting sub render state to the global scheme render state.}
        \textcolor{comment}{// It will override the default FFP lighting sub render state.}
        \textcolor{keywordflow}{if} (usePerPixelLighting) \{
            \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state}{Ogre::RTShader::SubRenderState}* perPixelLightModel =
                mShaderGenerator->createSubRenderState(
      \hyperlink{class_ogre_1_1_r_t_shader_1_1_per_pixel_lighting_ae766f76cad4b3a4339a0cd50abbddcc2}{Ogre::RTShader::PerPixelLighting::Type});

            schemRenderState->\hyperlink{class_ogre_1_1_r_t_shader_1_1_render_state_af66edaf33c654e03ef89f1eaec384a1f}{addTemplateSubRenderState}(perPixelLightModel);
        \}
\end{DoxyCodeInclude}
 any non F\+FP S\+RS will automatically override the default S\+RS for the same stage. \hyperlink{group___r_t_shader_gga4c92eba13eb8038d35530610c58ceff4a4981bd811954d8abdb7623226e81d9ab}{Ogre\+::\+R\+T\+Shader\+::\+F\+F\+P\+\_\+\+L\+I\+G\+H\+T\+I\+NG} in this case.\hypertarget{rtss_rtss_custom_mat}{}\paragraph{Customizing the R\+T\+S\+S using Material Scripts}\label{rtss_rtss_custom_mat}
Alternatively you can enable per-\/pixel lighting for one material only, by adding a {\ttfamily rtshader\+\_\+system} section to the pass as following


\begin{DoxyCodeInclude}
            \textcolor{comment}{// RT Shader system section.}
            rtshader\_system
            \{       
                \textcolor{comment}{// Override lighting stage with per pixel lighting.             }
                lighting\_stage per\_pixel                
            \}   
\end{DoxyCodeInclude}
 for more examples see {\ttfamily Samples/\+Media/\+R\+T\+Shader\+Lib/materials/\+R\+T\+Shader\+System.\+material}.

Here are the attributes you can use in a {\ttfamily rtshader\+\_\+system} section of a .material script\+:


\begin{DoxyItemize}
\item \href{#lighting_stage}{\tt lighting\+\_\+stage}
\item \href{#light_count}{\tt light\+\_\+count}
\item \href{#triplanarTexturing}{\tt triplanar\+Texturing}
\item \href{#integrated_pssm4}{\tt integrated\+\_\+pssm4}
\item \href{#layered_blend}{\tt layered\+\_\+blend}
\item \href{#source_modifier}{\tt source\+\_\+modifier}
\end{DoxyItemize}

\label{_lighting_stage}%


\subsubsection*{lighting\+\_\+stage}

Force a specific lighting model.

\begin{DoxyParagraph}{}
Format1\+: {\ttfamily lighting\+\_\+stage $<$ffp$\vert$per\+\_\+pixel$>$} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Format2\+: {\ttfamily lighting\+\_\+stage normal\+\_\+map $<$texturename$>$ \mbox{[}tangent\+\_\+space$\vert$object\+\_\+space\mbox{]} \mbox{[}coordinate\+Index\mbox{]} \mbox{[}none$\vert$bilinear$\vert$trilinear$\vert$anisotropic\mbox{]} \mbox{[}max\+\_\+anisotropy\mbox{]} \mbox{[}mipmap\+\_\+bias\mbox{]}} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: {\ttfamily lighting\+\_\+stage normal\+\_\+map Panels\+\_\+\+Normal\+\_\+\+Tangent.\+png tangent\+\_\+space 0 bilinear 1 -\/1.\+0}
\end{DoxyParagraph}
\begin{DoxySeeAlso}{See also}
\hyperlink{class_ogre_1_1_r_t_shader_1_1_normal_map_lighting_adc6b4bdd1ea31c2232336599d2b30b60}{Ogre\+::\+R\+T\+Shader\+::\+Normal\+Map\+Lighting\+::\+Normal\+Map\+Space} 

\hyperlink{group___general_ga21a0186392e9c9ce16d29c5568a773c5}{Ogre\+::\+Texture\+Filter\+Options}
\end{DoxySeeAlso}
\label{_light_count}%


\subsubsection*{light\+\_\+count}

Override dynamic light count. Allows to customize which lights the R\+T\+SS will consider. \begin{DoxyParagraph}{}
Format\+: {\ttfamily light\+\_\+count $<$point\+Lights$>$ $<$directional\+Lights$>$ $<$spot\+Lights$>$}
\end{DoxyParagraph}
\label{_triplanarTexturing}%


\subsubsection*{triplanar\+Texturing}

Force \href{https://www.volume-gfx.com/volume-rendering/triplanar-texturing/}{\tt triplanar texturing} \begin{DoxyParagraph}{}
Format\+: {\ttfamily triplanar\+Texturing $<$texture\+Scale$>$ $<$plateau\+Size$>$ $<$transition\+Speed$>$ $<$texture\+FromX$>$ $<$texture\+FromY$>$ $<$texture\+FromZ$>$} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: {\ttfamily triplanar\+Texturing 0.\+05 0.\+2 4.\+0 Bumpy\+Metal.\+jpg egyptrockyfull.\+jpg Mtl\+Plat2.\+jpg}
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em texture\+Scale} & texture coordinates are multiplied by this. \\
\hline
{\em plateau\+Size} & plateau on which small components of the normal have no influence. \\
\hline
{\em transition\+Speed} & transitions speed between the three textures Valid values are \mbox{[}0; 0.\+57\mbox{]} not bigger to avoid division by zero \\
\hline
{\em texture\+FromX} & Texture for the x-\/direction planar mapping \\
\hline
{\em texture\+FromY} & Texture for the y-\/direction planar mapping \\
\hline
{\em texture\+FromZ} & Texture for the z-\/direction planar mapping\\
\hline
\end{DoxyParams}
\label{_integrated_pssm4}%


\subsubsection*{integrated\+\_\+pssm4}

Integrated P\+S\+SM shadow receiver with 3 splits. Custom split points. \begin{DoxyParagraph}{}
Format\+: {\ttfamily integrated\+\_\+pssm4 $<$sp0$>$ $<$sp1$>$ $<$sp2$>$ $<$sp3$>$}
\end{DoxyParagraph}
\label{_layered_blend}%


\subsubsection*{layered\+\_\+blend}

Apply photoshop-\/like blend effects to texture layers \begin{DoxyParagraph}{}
Format\+: {\ttfamily layered\+\_\+blend $<$effect$>$} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: layered\+\_\+blend luminosity
\end{DoxyParagraph}
\begin{DoxyNote}{Note}
only applicable inside a texture\+\_\+unit section
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em effect} & one of {\ttfamily default, normal, lighten, darken, multiply, average, add, subtract, difference, negation, exclusion, screen, overlay, hard\+\_\+light, soft\+\_\+light, color\+\_\+dodge, color\+\_\+burn, linear\+\_\+dodge, linear\+\_\+burn, linear\+\_\+light, vivid\+\_\+light, pin\+\_\+light, hard\+\_\+mix, reflect, glow, phoenix, saturation, color, luminosity}\\
\hline
\end{DoxyParams}
\label{_source_modifier}%


\subsubsection*{source\+\_\+modifier}

Apply custom modulate effect to texture layer \begin{DoxyParagraph}{}
Format\+: {\ttfamily source\+\_\+modifier $<$operation$>$ custom $<$parameter\+Num$>$} 
\end{DoxyParagraph}
\begin{DoxyParagraph}{}
Example\+: {\ttfamily source\+\_\+modifier src1\+\_\+inverse\+\_\+modulate custom 2}
\end{DoxyParagraph}
\begin{DoxyNote}{Note}
only applicable inside a texture\+\_\+unit section
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em operation} & one of {\ttfamily src1\+\_\+modulate, src2\+\_\+modulate, src1\+\_\+inverse\+\_\+modulate, src2\+\_\+inverse\+\_\+modulate} \\
\hline
{\em parameter\+Num} & number of the custom shader parameter that controls the operation\\
\hline
\end{DoxyParams}
\hypertarget{rtss_rtss_indepth}{}\subsubsection{The R\+T\+S\+S in Depth}\label{rtss_rtss_indepth}
When the user asks the system to generate shaders for a given technique it has to provide the system a name for the target technique scheme. The system in turn, then creates a new technique based on the source technique but with a different scheme name. {\bfseries Note\+:} In order to avoid clashes the source technique must N\+OT contain any shaders otherwise this step will fail.

The idea behind this concept is to use \hyperlink{namespace_ogre}{Ogre}\textquotesingle{}s built in mechanism of material schemes, so all the user has to do in order to use the new technique is to change the material scheme of his viewport(s).

Before each viewport update, the system performs a validation step of all associated shader based techniques it created. This step includes automatic synchronization with the scene lights and fog states. When the system detects that a scheme is out of date it generates the appropriate shaders for each technique new.

The following steps are executed in order to generate shaders for a given technique\+:


\begin{DoxyItemize}
\item For each pass in the technique the system builds a set of sub render states that describe the logic process of the rendering pipeline from the draw call submission until the final pixel color.
\item Each render state is translated into a set of logic shader programs (currently only pixel and vertex shader). The logic programs are then sent to specific shader language writers that produce source code for the respective shader language. The source code is used to create the G\+PU programs that are applied to the destination pass. Before rendering of an object that uses generated shaders the system allows each sub render state to update the G\+PU constants associated with it.
\end{DoxyItemize}

\subsection*{Initializing the system}

\begin{DoxyNote}{Note}
If you are using the \hyperlink{class_ogre_bites_1_1_application_context}{Ogre\+Bites\+::\+Application\+Context}, the following steps will be taken automatically for you.
\end{DoxyNote}
Initializing the system is composed of the following steps\+:
\begin{DoxyItemize}
\item Create the internal managers and structures via the {\ttfamily \hyperlink{class_ogre_1_1_r_t_shader_1_1_shader_generator_ad206fa320c81f6482dbe6898a2aec260}{Ogre\+::\+R\+T\+Shader\+::\+Shader\+Generator\+::initialize()}} method.
\item Set the target cache path. This is the place on your disk where the output shaders will be written to or will be read from in case they were generated by previous runs of your application.
\item Verify that the location of the shader libs needed by the system is added to the Resource\+Group\+Manager via the {\ttfamily \hyperlink{class_ogre_1_1_resource_group_manager_a6ff0efec5d27cedb448cfba8b2b78c8d}{Ogre\+::\+Resource\+Group\+Manager\+::add\+Resource\+Location()}} method.
\item Assign the target scene manager to the shader generator.
\item Add one or more specialized sub-\/render states that are to be shared among all materials (per pixel lighting, textured fog, etc...).
\end{DoxyItemize}


\begin{DoxyCode}
\textcolor{keywordflow}{if} (\hyperlink{class_ogre_1_1_r_t_shader_1_1_shader_generator_ad206fa320c81f6482dbe6898a2aec260}{Ogre::RTShader::ShaderGenerator::initialize}())
\{
    \textcolor{comment}{// Grab the shader generator pointer.}
    mShaderGenerator = \hyperlink{class_ogre_1_1_r_t_shader_1_1_shader_generator_acd96bb2cad55be69d0fe8c6dc28d3590}{Ogre::RTShader::ShaderGenerator::getSingletonPtr}
      ();

    \textcolor{comment}{// Add the shader libs resource location. a sample shader lib can be found in Samples\(\backslash\)Media\(\backslash\)RTShaderLib}
    \hyperlink{class_ogre_1_1_resource_group_manager_a45101333f0f9ff132fc381dd5c4a1d60}{Ogre::ResourceGroupManager::getSingleton}().
      \hyperlink{class_ogre_1_1_resource_group_manager_a6ff0efec5d27cedb448cfba8b2b78c8d}{addResourceLocation}(shaderLibPath, \textcolor{stringliteral}{"FileSystem"});

    \textcolor{comment}{// Set shader cache path.}
    mShaderGenerator->setShaderCachePath(shaderCachePath);      

    \textcolor{comment}{// Set the scene manager.}
    mShaderGenerator->addSceneManager(sceneMgr);

    \textcolor{keywordflow}{return} \textcolor{keyword}{true};
\}
\end{DoxyCode}


\subsection*{Creating shader based technique}

This step will associate the given technique with a destination shader generated based technique. Calling the {\ttfamily \hyperlink{class_ogre_1_1_r_t_shader_1_1_shader_generator_af02d3e93da75e66ed3312b5790d18868}{Ogre\+::\+R\+T\+Shader\+::\+Shader\+Generator\+::create\+Shader\+Based\+Technique()}} will cause the system to generate internal data structures associated with the source technique and will add new technique to the source material. This new technique will have the scheme name that was passed as an argument to this method and all its passes will contain shaders that the system will generate and update during the application runtime.

To use the generated technique set the change material scheme of your viewport(s) to the same scheme name you passed as argument to this method.

Note that you can automate the shader generation process for all materials. First set the viewport scheme to the destination scheme of the R\+T\+SS shaders. Second register to the {\ttfamily \hyperlink{class_ogre_1_1_material_manager_1_1_listener}{Ogre\+::\+Material\+Manager\+::\+Listener}} and implement the {\ttfamily handle\+Scheme\+Not\+Found()} function. If the function requests a scheme for the R\+T\+SS, generate it based on functions parameters.


\begin{DoxyCode}
\textcolor{comment}{// Create shader based technique from the default technique of the given material.}
mShaderGenerator->createShaderBasedTechnique(\textcolor{stringliteral}{"Examples/BeachStones"}, 
      \hyperlink{class_ogre_1_1_material_manager_a290b828b5d44637ee4d247a09ea81bd6}{Ogre::MaterialManager::DEFAULT\_SCHEME\_NAME}, 
      \hyperlink{class_ogre_1_1_r_t_shader_1_1_shader_generator_a50a41bdc60047796354703d8d77d028a}{Ogre::RTShader::ShaderGenerator::DEFAULT\_SCHEME\_NAME});

\textcolor{comment}{// Apply the shader generated based techniques.}
mViewport->setMaterialScheme(
      \hyperlink{class_ogre_1_1_r_t_shader_1_1_shader_generator_a50a41bdc60047796354703d8d77d028a}{Ogre::RTShader::ShaderGenerator::DEFAULT\_SCHEME\_NAME});
\end{DoxyCode}
 

\subsection*{Runtime shader generation}

During the application runtime the Shader\+Generator instance receives notifications on per frame basis from its target Scene\+Manager. At this point it checks the material scheme in use. In case the current scheme has representations in the manager, it executes its validate method. The S\+G\+Scheme validation includes synchronization with scene light and fog settings. In case it is out of date it will rebuild all shader generated techniques. The first step is to loop over every S\+G\+Technique associated with this S\+G\+Scheme and build its Render\+States -\/ one for each pass. Each Render\+State has its own hash code and it is cached at the Shader\+Generator. The same Render\+State can be shared by multiple S\+G\+Passes. The second step is to loop again on every S\+G\+Technique and acquire a program set for each S\+G\+Pass. The actual acquiring process is done by the Program\+Manager that generates C\+PU program representation, send them to a matching Program\+Writer that is chosen by the active target language, the writer generates source code that is the basis for the G\+PU programs. The result of this entire process is that each technique associated with the S\+G\+Scheme has vertex and pixel shaders applied to all its passes. These shaders are synchronized with scene lights and fog settings.

\hypertarget{rtss_rtss__components}{}\paragraph{Main components}\label{rtss_rtss__components}
The following is an partial list of components within the R\+T\+SS. These components are listed as they have great importance in understanding controlling and later extending the R\+T\+SS system.

\subsubsection*{Shader\+Generator}

The Shader\+Generator is the main interface to the R\+T\+SS system. Through it you can request to generate and destroy the shaders, influence from what parts to create the shaders, and control general system settings such as the shading language and shader caching.

\subsubsection*{Render\+State classes}

A render state describes the different components that a shader will be created from. These components are referred to as Sub\+Render\+States.

Render\+States exist on 2 levels\+: scheme and pass. Scheme Render\+States describe the Sub\+Render\+States that will be used when creating a shader for a given material scheme. Pass Render\+State describe the Sub\+Render\+States that will be used when creating a specific pass of a specific material. When a shader is generated for a given material the system combines the Sub\+Render\+States from both Render\+States to create a shader specific for a material pass in a specific scheme.

\subsubsection*{Sub\+Render\+State classes}

Sub-\/render states (S\+RS) are components designed to generate the code of the R\+T\+SS shaders. Each S\+RS usually has a specific role to fill within the shader\textquotesingle{}s construction. These components can be combined in different combinations to create shaders with different capabilities.

There are 5 basic S\+R\+Ss. These are used to recreate the functionality provided by the fixed pipeline and are added by default to every scheme Render\+State\+:
\begin{DoxyItemize}
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_f_f_p_transform}{Ogre\+::\+R\+T\+Shader\+::\+F\+F\+P\+Transform} -\/ responsible for adding code to the vertex shader which computes the position of the vertex in projection space
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_f_f_p_colour}{Ogre\+::\+R\+T\+Shader\+::\+F\+F\+P\+Colour} -\/ responsible for adding code to the shaders that calculate the base diffuse and specular color of the object regardless of lights or textures. The color is calculated based on the ambient, diffuse, specular and emissive properties of the object and scene, color tracking and the specified hardware buffer color.
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_f_f_p_lighting}{Ogre\+::\+R\+T\+Shader\+::\+F\+F\+P\+Lighting} -\/ responsible for adding code to the shaders that calculate the luminescence added to the object by light. Then add that value to the color calculated by the color S\+RS stage.
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_f_f_p_texturing}{Ogre\+::\+R\+T\+Shader\+::\+F\+F\+P\+Texturing} -\/ responsible for adding code that modulates the color of the pixels based on textures assigned to the material.
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_f_f_p_fog}{Ogre\+::\+R\+T\+Shader\+::\+F\+F\+P\+Fog} -\/ responsible for adding code that modulates the color of a pixel based on the scene or object fog parameters.
\end{DoxyItemize}

There are many more sub render states that already exist in the \hyperlink{namespace_ogre}{Ogre} system and new ones can be added. Some of the existing S\+R\+Ss include capabilities such as\+: per-\/pixel lighting, texture atlas, advanced texture blend, bump mapping, efficient multiple lights (sample), textured fog (sample), etc...

\subsubsection*{Sub\+Render\+State\+Factory}

As the name suggests, sub render state factories are factories that produce sub render states. Each factory generates a specific S\+RS.

These type of components are note worthy for 2 reason. The first and obvious one is that they allow the system to generate new S\+R\+Ss for the materials it is asked to generate. The second reason is that they perform as script readers and writers allowing the system to create specific or specialized S\+R\+Ss per material.\hypertarget{rtss_creating-extensions}{}\paragraph{Creating custom shader extensions}\label{rtss_creating-extensions}
Although the system implements some common shader based effects such as per pixel lighting, normal map, etc., you may find it useful to write your own shader extensions.

In order to extend the system with your own shader effects you\textquotesingle{}ll have to follow these steps\+:
\begin{DoxyItemize}
\item Implement the Sub\+Render\+State interface -\/ This is the main class that is responsible for the actual effect processing such as preparing the destination pass, updating the C\+PU shader programs, updating the G\+PU shader parameters etc.
\item Implement the Sub\+Render\+State\+Factory interface\+: This class will allow the R\+T\+SS to create instances of the previous class via code or script as well as export it to material script file.
\item Register the factory to the R\+T\+SS using the \hyperlink{class_ogre_1_1_r_t_shader_1_1_shader_generator_ac266946244d79b2d4732607ae9479bd9}{Ogre\+::\+R\+T\+Shader\+::\+Shader\+Generator\+::add\+Sub\+Render\+State\+Factory} method.
\item Add shader files that will supply all the actual shader functions your Sub\+Render\+State needs. In order to support multiple shader languages you should supply code for your entire desired target shading languages (CG, H\+L\+SL, G\+L\+SL etc). These files should be placed in a way that the resource manager could access them. This can be done by placing them in a valid resource location or by dynamically adding resource location.
\end{DoxyItemize}

Implementing the Sub\+Render\+State requires overriding the pure methods of the base class.
\begin{DoxyItemize}
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state_ae91b7b8f76848d67652b6e5832a27a49}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+::get\+Type()} should return unique string that identify the sub class implementation. That value is shared among all instances and can be stored in a static string variable. It uses to system to match between Sub\+Render\+State instance and the factory to should destroy it.
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state_acb48c34ee231f0220f68c967fb32f1e5}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+::get\+Execution\+Order()} should return integer value that will use the system to sort all Sub\+Render\+State instances of the same render state before each one of them will create its part in the C\+PU shader programs. Note that\+:
\begin{DoxyItemize}
\item The execution order does not imply the order of the parameter definitions and function calls within the generated shader.
\item If an execution number is set to be the same as one of the basic fixed pipeline S\+R\+Ss. Than that S\+RS will be built {\bfseries instead} of the fixed pipeline S\+RS.
\end{DoxyItemize}
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state_a5dfe9f03413e0fe99ea2640f06c1f13c}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+::copy\+From()} a simple copy method that uses the system when coping one instance to another. {\bfseries Note\+:} Only configuration data attributes should be copy here.
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state_a4b43c261946926ebbc6456deccc6697a}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+::create\+Cpu\+Sub\+Programs} -\/ This is the heart of this interface. This method should update the C\+PU shader programs with the specific details of the overriding class.
\end{DoxyItemize}

The Sub\+Render\+State supply default implementation for this method which break down this method into three stages\+:
\begin{DoxyItemize}
\item Resolving parameters\+: this stage should grab all the needed parameters for this Sub\+Rrender\+State. In case of the F\+F\+P\+Transform it should resolve the world view projection matrix and vertex shader input and output position parameters.
\end{DoxyItemize}


\begin{DoxyCodeInclude}
    Program* vsProgram = programSet->getCpuProgram(\hyperlink{group___resources_ggad08e89fa63e81d061ea9e2f37664976ea3d96c54ace718f26c66067503efd56a3}{GPT\_VERTEX\_PROGRAM});
    Function* vsEntry = vsProgram->getEntryPointFunction();
    
    \textcolor{comment}{// Resolve World View Projection Matrix.}
    \hyperlink{namespace_ogre_1_1_r_t_shader_a492843278bb5c3f7c535cc2a516c436f}{UniformParameterPtr} wvpMatrix = vsProgram->resolveAutoParameterInt(
      GpuProgramParameters::ACT\_WORLDVIEWPROJ\_MATRIX, 0);
        
    \textcolor{comment}{// Resolve input position parameter.}
    \hyperlink{namespace_ogre_1_1_r_t_shader_a0073f878d77367ce3ccea68a6a44a1e9}{ParameterPtr} positionIn = vsEntry->resolveInputParameter(Parameter::SPS\_POSITION, 0, 
      Parameter::SPC\_POSITION\_OBJECT\_SPACE, \hyperlink{group___materials_gga9c5b2950be06ff56a6ee0bace240d447a466febc90367dab6c895c98edfff7681}{GCT\_FLOAT4}); 
    
    \textcolor{comment}{// Resolve output position parameter.}
    \hyperlink{namespace_ogre_1_1_r_t_shader_a0073f878d77367ce3ccea68a6a44a1e9}{ParameterPtr} positionOut = vsEntry->resolveOutputParameter(Parameter::SPS\_POSITION, 0, 
      Parameter::SPC\_POSITION\_PROJECTIVE\_SPACE, \hyperlink{group___materials_gga9c5b2950be06ff56a6ee0bace240d447a466febc90367dab6c895c98edfff7681}{GCT\_FLOAT4});

    \textcolor{keywordflow}{if} (!wvpMatrix || !positionIn || !positionOut)
    \{
        \hyperlink{group___general_gaf27f0d64dfeb225d37a513c253eaa1a0}{OGRE\_EXCEPT}( Exception::ERR\_INTERNAL\_ERROR, 
                \textcolor{stringliteral}{"Not all parameters could be constructed for the sub-render state."},
                \textcolor{stringliteral}{"FFPTransform::createCpuSubPrograms"} );
    \}
\end{DoxyCodeInclude}

\begin{DoxyItemize}
\item Resolving dependencies\+: this stage should provide the name of the external shader library files that contains the actual shader code needed by this Sub\+Render\+State. In case of the F\+F\+P\+Texturing it will add the common and texturing library for both vertex and pixel shader program.
\end{DoxyItemize}


\begin{DoxyCodeInclude}
    Program* vsProgram = programSet->getCpuProgram(\hyperlink{group___resources_ggad08e89fa63e81d061ea9e2f37664976ea3d96c54ace718f26c66067503efd56a3}{GPT\_VERTEX\_PROGRAM});
    Program* psProgram = programSet->getCpuProgram(\hyperlink{group___resources_ggad08e89fa63e81d061ea9e2f37664976eac9a00b013e9075bc061b0585cf9a6c3b}{GPT\_FRAGMENT\_PROGRAM});

    vsProgram->addDependency(\hyperlink{group___r_t_shader_gaf315dcdcd0eeb960135ab30110ae77ba}{FFP\_LIB\_COMMON});
    vsProgram->addDependency(\hyperlink{group___r_t_shader_gab7d72f56d81dc214ac28a7e40bfa56c3}{FFP\_LIB\_TEXTURING});    
    psProgram->addDependency(\hyperlink{group___r_t_shader_gaf315dcdcd0eeb960135ab30110ae77ba}{FFP\_LIB\_COMMON});
    psProgram->addDependency(\hyperlink{group___r_t_shader_gab7d72f56d81dc214ac28a7e40bfa56c3}{FFP\_LIB\_TEXTURING});
\end{DoxyCodeInclude}

\begin{DoxyItemize}
\item Adding function invocations\+: this stage creates the function calls within this Sub\+Render\+State requires. Each function call has two keys that are used by the system to sort it before generating the actual shader code as well as set of in/out parameters. A function invocation is added to either vertex shader program or fragment shader program. In case of the F\+F\+P\+Fog it will add vertex depth calculation to the vertex shader program.
\end{DoxyItemize}


\begin{DoxyCodeInclude}
        curFuncInvocation = \hyperlink{group___general_gab5fc1358fd5a889de0a06d07e45df1ff}{OGRE\_NEW} FunctionInvocation(
      \hyperlink{group___r_t_shader_gabaab1e89270cd7f763f2f8e0258c400e}{FFP\_FUNC\_PIXELFOG\_DEPTH}, \hyperlink{group___r_t_shader_gga7d20b2397c3eab2b52ec405863c6f274a8b4930a3fd90d5b7222960fc5727b8cf}{FFP\_VS\_FOG});
        curFuncInvocation->pushOperand(mWorldViewProjMatrix, Operand::OPS\_IN);
        curFuncInvocation->pushOperand(mVSInPos, Operand::OPS\_IN);  
        curFuncInvocation->pushOperand(mVSOutDepth, Operand::OPS\_OUT);  
        vsMain->addAtomInstance(curFuncInvocation);     
\end{DoxyCodeInclude}
 Note\+:
\begin{DoxyItemize}
\item Each \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State} can add as many function invocations as it needs.
\item Each \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State} can different function invocations in different ordering.
\item The ordering of the function invocation is crucial. Use the F\+F\+P\+Vertex\+Shader\+Stage and F\+F\+P\+Fragment\+Shader\+Stage enumarations to place your invocations in the desired order.
\item Make sure the parameter semantic (in/out) in the Sub\+Render\+State code matches to your shader code implementation you supplied in the library file. G\+L\+SL will fail to link to libray functions if it won\textquotesingle{}t be able to find a perfect function declaration match.
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state_a4c2acbc15e44c3fe42868abce1116ec2}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+::update\+Gpu\+Programs\+Params} -\/ As the name suggest this method should be overridden only in case your Sub\+Render\+State should update some parameter it created before.
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state_afd08043cfad43a1ae470c3c1be341ba1}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+::pre\+Add\+To\+Render\+State()}\+: this method called before adding this Sub\+Render\+State to a parent Render\+State instances. It allows this Sub\+Render\+State to exclude itself from the list in case the source pass is not matching. I.\+E in case of Sub\+Render\+State that perform lighting calculations it can return false when the given source pass specifies that lighting calculations disabled for it.
\end{DoxyItemize}


\begin{DoxyCodeInclude}
    \textcolor{keywordflow}{if} (!srcPass->getLightingEnabled())
        \textcolor{keywordflow}{return} \textcolor{keyword}{false};
\end{DoxyCodeInclude}
 This method also let the Sub\+Render\+State to opportunity to modify the destination pass. I.\+E the Normal\+Map\+Lighting instance adds the normal map texture unit in this context.

Implementing the \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state_factory}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+Factory} is much simpler and involves implementing the following methods
\begin{DoxyItemize}
\item Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+Factory\+::create\+Instance\+Impl()\+: This method should return instance for the Sub\+Render\+State sub class.
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state_factory_a14ce88a3c6833585ec73b77b7536b441}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+Factory\+::create\+Instance()}\+: This method should return instasnce for the Sub\+Render\+State sub class using the given script compiler parameters. Implemet this method if you want to be able to creat your custom shader extension from material script.
\item \hyperlink{class_ogre_1_1_r_t_shader_1_1_sub_render_state_factory_ada31909080bae96784504be42d9bd77c}{Ogre\+::\+R\+T\+Shader\+::\+Sub\+Render\+State\+Factory\+::write\+Instance()}\+: This method should write down the parameters of a given Sub\+Render\+State instance to material script file. Implement this method if you want to be able to export a material that contains your custom shader extension.
\end{DoxyItemize}\hypertarget{rtss_debugging}{}\paragraph{Tips for debugging shaders}\label{rtss_debugging}
A couple of notes on debugging shaders coming from the R\+T\+SS\+:
\begin{DoxyItemize}
\item Call \hyperlink{class_ogre_bites_1_1_application_context_aaad4c1d25a7a5f60dd5c5f3812f1096b}{Ogre\+Bites\+::\+Application\+Context\+::set\+R\+T\+S\+S\+Write\+Shaders\+To\+Disk}. This will cache the generated shaders onto the disk under the directory {\ttfamily \{\hyperlink{namespace_ogre}{Ogre} directory\}\textbackslash{}Samples\textbackslash{}Media\textbackslash{}R\+T\+Shader\+Lib\textbackslash{}cache}. This is important for 2 reasons\+:
\begin{DoxyItemize}
\item It will make compilation problems easier to detect.
\item Once a shader is written to the disk, as long as you don\textquotesingle{}t change the code behind it, the same shader will be picked up in the next application run even if its content has changed. If you have compilation or visual problems with the shader you can try to manually tinker with it without compiling the code again and again.
\end{DoxyItemize}
\item Find the file Ogre\+Shader\+Program\+Manager.\+cpp and add a breakpoint at {\ttfamily p\+Gpu\+Program.\+set\+Null();} (in create\+Gpu\+Program). If a shader will fail to compile it will usually fail there. Once that happens you can find the shader name under the {\ttfamily program\+Name} parameter, then look for it in the cache directory you created.
\item Other common problems with creating shaders in R\+T\+SS usually occur from defining vertex shader parameters and using them in the pixel shader and vice versa. so watch out for those. 
\end{DoxyItemize}\hypertarget{hlms}{}\subsection{H\+L\+MS\+: High Level Material System}\label{hlms}
This component allows you to manage shader variations of a specific shader template. It is a different take to the Uber shader management, but instead of using plain {\ttfamily \#ifdefs} it uses a custom, more powerful preprocessor language.

Additionally it allows you to define a set of abstract properties that are then used to configure the shader generation.

Currently there is only the Physically Based Shading (P\+BS) material implementation based on the H\+L\+MS that does not read the classical Materials and therefore does not respect the settings for fog, diffuse\+\_\+color etc.

\begin{DoxyAttention}{Attention}
This documentation was originally written for Ogre 2.\+1, so not all details apply to the actual H\+L\+MS backport.
\end{DoxyAttention}
\hypertarget{hlms_components}{}\subsubsection{The three components}\label{hlms_components}



\begin{DoxyEnumerate}
\item Scripts. To set the material properties (i.\+e. type of Hlms to use\+: P\+BS, Toon shading, G\+UI; what textures, diffuse colour, roughness, etc). {\bfseries You currently have to do this from C++.} Everybody will be using this part.
\item Shader template. The Hlms takes a couple hand-\/written glsl/hlsl files as template and then adapts it to fit the needs on the fly (i.\+e. if the mesh doesn’t contain skeleton, the bit of code pertaining to skeletal animation is stripped from the vertex shader). The Hlms provides a simple preprocessor to deal with this entirely within from the template, but you’re not forced to use it. Here’s a simple example of the preprocessor. I won’t be explaining the main keywords today. Advanced users will probably want to modify these files (or write some of their own) to fit their custom needs.
\item C++ classes implementation. The C++ takes care of picking the shader templates and manipulating them before compiling; and most importantly it feeds the shaders with uniform/constans data and sets the textures that are being in use. It is extremely flexible, powerful, efficient and scalable, but it’s harder to use than good ol’ Materials because those used to be data-\/driven\+: there are no Auto\+Params\+Source here. Want the view matrix? You better grab it from the camera when the scene pass is about to start, and then pass it yourself to the shader. This is very powerful, because in D3\+D11/\+G\+L3+ you can just set the uniform buffer with the view matrix just once for the entire frame, and thus have multiple uniforms buffers sorted by update frequency. Very advanced user will be using messing with this part.
\end{DoxyEnumerate}

\begin{DoxyNote}{Note}
Material scripts in \hyperlink{namespace_ogre}{Ogre} 1.\+x do not yet support the H\+L\+MS -\/ you must use the C++ A\+PI. e.\+g. \hyperlink{class_ogre_1_1_pbs_material}{Ogre\+::\+Pbs\+Material}.
\end{DoxyNote}
Based on your skillset and needs, you can pick up to which parts you want to mess with. Most users will just use the scripts to define materials, advanced users will change the template, and very advanced users who need something entirely different will change all three.

For example the P\+BS material has its own C++ implementation and its own set of shader templates. The Toon Shading has its own C++ implementation and set of shaders.

It is theoretically possible to implement both Toon \& P\+BS in the same C++ module, but that would be crazy, hard to maintain and not very modular.\hypertarget{hlms_data}{}\subsubsection{Material parameters are stored in “\+Blocks”}\label{hlms_data}
You could be thinking the reason I came up with these two is to fit with D3\+D11′s grand scheme of things while being compatible with Open\+GL. But that’s a half truth and an awesome side effect. I’ve been developing the Hlms using Open\+GL this whole time.

An Open\+GL fan will tell you that grouping these together in single call like D3\+D11 did barely reduce A\+PI overhead in practice (as long as you keep sorting by state), and they’re right about that.

However, there are big advantages for using blocks\+:


\begin{DoxyEnumerate}
\item Many materials in practice share the same Macro-\/ \& Blendblock parameters. In an age where we want many 3D primitives with the same shader but slightly different parameters like texture, colour, or roughness (which equals, a different material) having these settings repeated per material wastes a lot of memory space… and a lot of bandwidth (and wastes cache space). \hyperlink{namespace_ogre}{Ogre} 2.\+0 is bandwidth bound, so having all materials share the same pointer to the same Macroblock can potentially save a lot of bandwidth, and be friendlier to the cache at the same time.\+This stays true whether we use D3\+D11, D3\+D12, Open\+GL, GL ES 2, or Mantle.
\item Sorting by Macroblock is a lot easier (and faster) than sorting by its individual parameters\+: when preparing the hash used for sorting, it’s much easier to just do (every frame, per object) {\ttfamily hash $\vert$= (macroblock-\/$>$get\+Id() $<$$<$ bits) \& mask} than to do\+: {\ttfamily hash =$\vert$ m-\/$>$depth\+\_\+check $\vert$ m-\/$>$depth\+Write $<$$<$ 1 $\vert$ m-\/$>$depth\+Bias $<$$<$ 2 $\vert$ m-\/$>$depth\+\_\+slope\+\_\+bias $<$$<$ 3 $\vert$ m-\/$>$cull\+Mode $<$$<$ 18 $\vert$ ... ;} We also need a lot more bits we can’t afford. \hyperlink{namespace_ogre}{Ogre} 2.\+0 imposes a limit on the amount of live Macroblocks you can have at the same time; as we run out of hashing space (by the way, D3\+D11 has its own limit). It operates around the idea that most setting combinations won’t be used in practice.
\end{DoxyEnumerate}

Of course it’s not perfect, it can’t fit every use case. We inherit the same problems D3\+D11 has. If a particular rendering technique relies on regularly changing a property that lives in a Macroblock (i.\+e. like alternating depth comparison function between less \& greater with every draw call, or gradually incrementing the depth bias on each draw call); you’ll end up redundantly changing a lot of other states (culling mode, polygon mode, depth check \& write flags, depth bias) alongside it. This is rare. We’re aiming the general use case.

These problems make me wonder if D3\+D11 made the right choice of using blocks from an A\+PI perspective, since I’m not used to driver development. However from an engine perspective, blocks make sense.\hypertarget{hlms_toc52}{}\paragraph{Datablocks}\label{hlms_toc52}
We’re introducing the concept of Datablocks. A Datablock is a “material” from the user’s perspective. It holds data (i.\+e. material properties) that will be passed directly to the shaders.



The diagram shows a typical layout of a datablock. Samplerblocks do not live inside base \hyperlink{class_ogre_1_1_hlms_datablock}{Ogre\+::\+Hlms\+Datablock}, but rather in its derived implementation. This is because some implementations may not need textures at all, and the number of samplerblocks is unknown. Some implementations may want one samplerblock per texture, whereas others may just need one.

\begin{DoxyNote}{Note}
Macroblocks and Blendblocks are not available in 1.\+x -\/ use \hyperlink{class_ogre_1_1_pass_ae454faee87f8cb0b8540810e48118788}{Ogre\+::\+Pass\+::set\+Depth\+Check\+Enabled} etc. as usual, to change the respective properties
\end{DoxyNote}
\hypertarget{hlms_toc69}{}\subsubsection{Hlms templates}\label{hlms_toc69}
The Hlms will parse the template files from the template folder according to the following rules\+:


\begin{DoxyEnumerate}
\item The files with the names \char`\"{}\+Vertex\+Shader\+\_\+vs\char`\"{}, \char`\"{}\+Pixel\+Shader\+\_\+ps\char`\"{}, \char`\"{}\+Geometry\+Shader\+\_\+gs\char`\"{}, \char`\"{}\+Hull\+Shader\+\_\+hs\char`\"{}, \char`\"{}\+Domain\+Shader\+\_\+ds\char`\"{} will be fully parsed and compiled into the shader. If an implementation only provides \char`\"{}\+Vertex\+Shader\+\_\+vs.\+glslt\char`\"{}, \char`\"{}\+Pixel\+Shader\+\_\+ps.\+glslt\char`\"{}; only the vertex and pixel shaders for Open\+GL will be created. There will be no geometry or tesellation shaders.
\item The files that contain the string \char`\"{}\+\_\+piece\+\_\+vs\char`\"{} in their filenames will be parsed only for collecting pieces (more on pieces later). Likewise, the words \char`\"{}\+\_\+piece\+\_\+ps\char`\"{}, \char`\"{}\+\_\+piece\+\_\+gs\char`\"{}, \char`\"{}\+\_\+piece\+\_\+hs\char`\"{}, "\+\_\+piece\+\_\+ds” correspond to the pieces for their respective shader stages. Note that you can concatenate, thus "My\+Utilities\+\_\+piece\+\_\+vs\+\_\+piece\+\_\+ps.\+glslt” will be collected both in the vertex and pixel shader stages.
\end{DoxyEnumerate}

The Hlms takes a template file (i.\+e. a file written in G\+L\+SL or H\+L\+SL) and spits out valid shader code. Templates can take advantage of the Hlms\textquotesingle{} preprocessor, which is a simple yet powerful macro-\/like preprocessor that helps writing the required code.\hypertarget{hlms_preproc}{}\paragraph{The Hlms preprocessor}\label{hlms_preproc}
The preprocessor was written with speed and simplicity in mind. It does not implement an A\+ST or anything fancy. This is very important to account while writing templates because there will be cases when using the preprocessor may feel counter-\/intuitive or frustrating.

For example 
\begin{DoxyCode}
\(\backslash\)\textcolor{keyword}{@property}( IncludeLighting )

\textcolor{comment}{/* code here */}

@end
\end{DoxyCode}


is analogous to 
\begin{DoxyCode}
\textcolor{preprocessor}{#if IncludeLighting != 0}

\textcolor{comment}{/* code here */}

\textcolor{preprocessor}{#endif}
\end{DoxyCode}


However you can\textquotesingle{}t evaluate Include\+Lighting to anything other than zero and non-\/zero, i.\+e. you can\textquotesingle{}t check whether Include\+Lighting == 2 with the Hlms preprocessor. A simple workaround is to define, from C++, the variable “\+Include\+Lighting\+Equals2” and check whether it\textquotesingle{}s non-\/zero. Another solution is to use the G\+L\+S\+L/\+H\+L\+SL preprocessor itself instead of Hlms\textquotesingle{}. However, the advantage of Hlms is that you can see its generated output in a file for inspection, whereas you can\textquotesingle{}t see the G\+L\+S\+L/\+H\+L\+SL after the macro preprocessor without vendor-\/specific tools. Plus, in the case of G\+L\+SL, you\textquotesingle{}ll depend on the driver implementation having a good macro preprocessor.\hypertarget{hlms_syntax}{}\paragraph{Preprocessor syntax}\label{hlms_syntax}
The preprocessor always starts with @ followed by the command, and often with arguments inside parenthesis. Note that the preprocessor is always case-\/sensitive. The following keywords are recognized\+:


\begin{DoxyItemize}
\item @property
\item @foreach
\item @counter
\item @value
\item @set add sub mul div mod min max
\item @piece
\item @insertpiece
\item @pset padd psub pmul pdiv pmod pmin pmax
\end{DoxyItemize}

\subsubsection*{@property( expression )}

Checks whether the variables in the expression are true, if so, the text inside the block is printed. Must be finazlied with @end. The expression is case-\/sensitive. When the variable hasn\textquotesingle{}t been declared, it evaluates to false.

The logical operands \&\& $\vert$$\vert$ ! are valid.

Examples\+: 
\begin{DoxyCode}
\(\backslash\)\textcolor{keyword}{@property}( hlms\_skeleton )

\textcolor{comment}{//Skeleton animation code here}

\textcolor{keyword}{@end}

\(\backslash\)\textcolor{keyword}{@property}( hlms\_skeleton && !hlms\_normal )

\textcolor{comment}{//Print this code if it has skeleton animation but no normals}

\textcolor{keyword}{@end}

\(\backslash\)\textcolor{keyword}{@property}( hlms\_normal || hlms\_tangent )

\textcolor{comment}{//Print this code if it has normals or tangents}

\textcolor{keyword}{@end}

\(\backslash\)\textcolor{keyword}{@property}( hlms\_normal && (!hlms\_skeleton || hlms\_tangent) )

\textcolor{comment}{//Print this code if it has normals and either no skeleton or tangents}

@end
\end{DoxyCode}


It is very similar to \#if hlms\+\_\+skeleton != 0 \#endif; however there is no equivalent \#else or \#elif syntax. As a simple workaround you can do\+: 
\begin{DoxyCode}
\(\backslash\)\textcolor{keyword}{@property}( hlms\_skeleton )

\textcolor{comment}{//Skeleton animation code here}

\textcolor{keyword}{@end} \(\backslash\)\textcolor{keyword}{@property}( !hlms\_skeleton )

\textcolor{comment}{//Non-Skeleton code here}

\textcolor{keyword}{@end}
\end{DoxyCode}


Newlines are not necessary. The following is perfectly valid\+: 
\begin{DoxyCode}
diffuse = surfaceDiffuse \(\backslash\)@property( hasLights )* lightDiffuse@end ;
\end{DoxyCode}


Which will print\+: 
\begin{DoxyCode}
hasLights != 0                              hasLights == 0
diffuse = surfaceDiffuse * lightDiffuse;   diffuse = surfaceDiffuse ;
\end{DoxyCode}


\subsubsection*{@foreach( scoped\+Var, count, \mbox{[}start\mbox{]} )}

Loop that prints the text inside the block, The text is repeated count -\/ start times. Must be finalized with @end.


\begin{DoxyItemize}
\item scoped\+Var is a variable that can be used to print the current iteration of the loop while inside the block. i.\+e. “@scoped\+Var” will be converted into a number in the range \mbox{[}start; count)
\item count The number of times to repeat the loop (if start = 0). Count can read variables.
\item start Optional. Allows to start from a value different than 0. Start can read variables.
\end{DoxyItemize}

Newlines are very important, as they will be printed with the loop.

Examples\+: \tabulinesep=1mm
\begin{longtabu} spread 0pt [c]{*{2}{|X[-1]}|}
\hline
\rowcolor{\tableheadbgcolor}\textbf{ Expression }&\textbf{ Output  }\\\cline{1-2}
\endfirsthead
\hline
\endfoot
\hline
\rowcolor{\tableheadbgcolor}\textbf{ Expression }&\textbf{ Output  }\\\cline{1-2}
\endhead
@foreach( 4, n ) ~\newline
\quad{} @n@end &~\newline
0~\newline
1~\newline
2~\newline
3 \\\cline{1-2}
@foreach( 4, n ) @n@end &0 1 2 3 \\\cline{1-2}
@foreach( 4, n )~\newline
\quad{}@n~\newline
@end &~\newline
0~\newline
~\newline
1~\newline
~\newline
2~\newline
~\newline
3~\newline
 \\\cline{1-2}
@foreach( 4, n, 2 ) @n@end &2 3 \\\cline{1-2}
@pset( my\+Start\+Var, 1 )~\newline
@pset( my\+Count\+Var, 3 )~\newline
@foreach( my\+Start\+Var, n, my\+Count\+Var )~\newline
\quad{}@n@end &1~\newline
2 \\\cline{1-2}
@foreach( 2, n )~\newline
\quad{}@insertpiece( piece\+Name@n )@end &@insertpiece( piece\+Name0 )~\newline
 @insertpiece( piece\+Name1 ) \\\cline{1-2}
\end{longtabu}
\begin{quote}
{\bfseries Attention \#1!}

Don\textquotesingle{}t use the common letter i for the loop counter. It will conflict with other keywords.

i.\+e. “@foreach( 1, i )@insertpiece( piece\+Name )@end” will print “0nsertpiece( piece\+Name )” which is probably not what you intended.

{\bfseries Attention \#2!}

foreach is parsed after property math (pset, padd, etc). That means that driving each iteration through a combination of properties and padd functions will not work as you would expect.

i.\+e. The following code will not work\+:


\begin{DoxyCode}
@pset( myVar, 1 )

@\textcolor{keywordflow}{foreach}( 2, n )

\textcolor{comment}{//Code}

@psub( myVar, 1 ) \textcolor{comment}{//Decrement myVar on each loop}

\(\backslash\)\textcolor{keyword}{@property}( myVar )

\textcolor{comment}{//Code that shouldn't be printed in the last iteration}

\textcolor{keyword}{@end}

@end
\end{DoxyCode}


Because psub will be evaluated before expanding the foreach. \end{quote}


\subsubsection*{@counter( variable )}

Prints the current value of variable and increments it by 1. If the variable hasn\textquotesingle{}t been declared yet, it is initialized to 0.

Examples\+: 
\begin{DoxyCode}
Expression          Output

@counter( myVar )   0

@counter( myVar )   1

@counter( myVar )   2
\end{DoxyCode}


\subsubsection*{@value( variable )}

Prints the current value of variable without incrementing it. If the variable hasn\textquotesingle{}t been declared, prints 0. 
\begin{DoxyCode}
Expression          Output

@value( myVar )     0

@value( myVar )     0

@counter( myVar )   0

@value( myVar )     1

@value( myVar )     1
\end{DoxyCode}


\subsubsection*{@set add sub mul div mod min max}

Sets a variable to a given value, adds, subtracts, multiplies, divides, calculates modulus, or the minimum/maximum of a variable and a constant, or two variables. This family of functions get evaluated after foreach(s) have been expanded and pieces have been inserted. Doesn\textquotesingle{}t print its value.

Arguments can be in the form @add(a, b) meaning a += b; or in the form @add( a, b, c ) meaning a = b + c

Useful in combination with @counter and @value

\tabulinesep=1mm
\begin{longtabu} spread 0pt [c]{*{3}{|X[-1]}|}
\hline
\rowcolor{\tableheadbgcolor}\textbf{ Expression }&\textbf{ Output }&\textbf{ Math  }\\\cline{1-3}
\endfirsthead
\hline
\endfoot
\hline
\rowcolor{\tableheadbgcolor}\textbf{ Expression }&\textbf{ Output }&\textbf{ Math  }\\\cline{1-3}
\endhead
@set( my\+Var, 1 ) ~\newline
 @value( my\+Var ) &1 &my\+Var = 1 \\\cline{1-3}
@add( my\+Var, 5 )~\newline
 @value( my\+Var ) &6 &my\+Var = 1 + 5 \\\cline{1-3}
@div( my\+Var, 2 ) ~\newline
 @value( my\+Var ) &3 &my\+Var = 6 / 2 \\\cline{1-3}
@mul( my\+Var, my\+Var )~\newline
 @value( my\+Var ) &9 &my\+Var = 3 $\ast$ 3 \\\cline{1-3}
@mod( my\+Var, 5 ) ~\newline
 @value( my\+Var ) &4 &my\+Var = 9 \% 5 \\\cline{1-3}
@add( my\+Var, 1, 1 ) ~\newline
 @value( my\+Var ) &2 &my\+Var = 1 + 1 \\\cline{1-3}
\end{longtabu}
\subsubsection*{@piece( name\+Of\+Piece )}

Saves all the text inside the blocks and saves it as a named piece. If a piece with the given name already exists, a compiler error will be thrown. The text that was inside the block won\textquotesingle{}t be printed. Useful when in combination with @insertpiece. Pieces can also be defined from C++ or \href{#toc69}{\tt {\itshape collected}} from piece template files.

Example\+: 
\begin{DoxyCode}
Expression                        Output

@piece( VertexTransform )         

outPos = worldViewProj * inPos   

\textcolor{keyword}{@end}
\end{DoxyCode}


\subsubsection*{@insertpiece( name\+Of\+Piece )}

Prints a block of text that was previously saved with piece (or from C++). If no piece with such name exists, prints nothing.

Example\+: 
\begin{DoxyCode}
Expression                                                     Output

@piece( VertexTransform )outPos = worldViewProj * inPos@end   void main()

void main()                                                    \{

\{                                                              outPos = worldViewProj * inPos

@insertpiece( VertexTransform )                                \}

@insertpiece( InexistentPiece )                                

\}
\end{DoxyCode}


\subsubsection*{@pset padd psub pmul pdiv pmod pmin pmax}

Analogous to \href{#toc304}{\tt {\itshape the family of math functions without the \textquotesingle{}p\textquotesingle{} prefix}}. The difference is that the math is evaluated before anything else. There is no much use to these functions, probably except for quickly testing whether a given flag/variable is being properly set from C++ without having to recompile.

i.\+e. If you suspect hlms\+\_\+normal is never being set, try @pset( hlms\+\_\+normal, 1 )

One important use worth mentioning, is that variables retain their values across shader stages. First the vertex shader template is parsed, then the pixel shader one. If \textquotesingle{}my\+Val\textquotesingle{} is 0 and the vertex shader contains @counter( my\+Val ); when the pixel shader is parsed @value( my\+Val ) will return 1, not 0.

If you need to reset these variables across shader stages, you can use pset( my\+Val, 0 ); which is guaranteed to reset your variable to 0 before anything else happens; even if the pset is stored in a piece file.\hypertarget{hlms_shaders}{}\subsubsection{Creation of shaders}\label{hlms_shaders}
There are two components that needs to be evaluated that may affect the shader itself and would need to be recompiled\+:


\begin{DoxyEnumerate}
\item The Datablock/\+Material. Does it have Normal maps? Then include code to sample the normal map and affect the lighting calculations. Does it have a diffuse map? If not, avoid sampling the diffuse map and multiplying it against the diffuse colour, etc.
\item The Mesh. Is it skeletally animated? Then include skeletal animation code. How many blend weights? Modify the skeletal animation code appropiately. It doesn\textquotesingle{}t have tangents? Then skip the normal map defined in the material. And so on.
\end{DoxyEnumerate}

When calling \hyperlink{class_ogre_1_1_scene_manager_a29ba8a2cad151d307d04781f749e7e84}{Ogre\+::\+Scene\+Manager\+::\+\_\+render\+Scene}, what happens is that \hyperlink{group___hlms_ga72e50c625adeeef2ca44ba7281c92574}{Ogre\+::\+Shader\+Manager\+::get\+Gpu\+Program} will get called and this function evaluates both the mesh and datablock compatibility.

If they\textquotesingle{}re compatible, all the variables (aka properties) and pieces are generated and cached in a structure (m\+Shader\+Cache) with a hash key to this cache entry. If a different pair of datablock-\/mesh ends up having the same properties and pieces, they will get the same hash (and share the same shader).

The following graph summarizes the process\+:



Later on during rendering, at the start each render pass, a similar process is done, which ends up generating a “\href{#toc567}{\tt {\itshape pass hash}}” instead of a renderable hash. Pass data stores settings like number of shadow casting lights, number of lights per type (directional, point, spot).

While iterating each renderable for render, the hash key is read from the Renderable and merged with the pass\textquotesingle{} hash. With the merged hash, the shader is retrieved from a cache. If it\textquotesingle{}s not in the cache, the shader will be generated and compiled by merging the cached data (pieces and variables) from the Renderable and the Pass. The following graph illustrates the process\+:

\hypertarget{hlms_cpp}{}\subsubsection{C++ interaction with shader templates}\label{hlms_cpp}
Note\+: This section is relevant to those seeking to write their own Hlms implementation.

C++ can use \hyperlink{group___hlms_ga650d837deeed1b6756ac0adb3f7b6eef}{Ogre\+::\+Hlms\+Material\+Base\+::get\+Property\+Map()}.set\+Property( \char`\"{}key\char`\"{}, value ) to set “key” to the given value. This value can be read by @property, @foreach, @add/sub/mul/div/mod, @counter, @value and @padd/psub/pmul/pdiv/pmod

To create pieces (or read them) you need to pass your custom Hlms\+::\+Pieces\+Map to Hlms\+::add\+Renderable\+Cache.

The recommended place to do this is in Hlms\+::calculate\+Hash\+For\+Pre\+Create and Hlms\+::calculate\+Hash\+For\+Pre\+Caster. Both are virtual. The former gets called right before adding the set of properties, pieces and hash to the cache, while the latter happens right before adding the similar set for the shadow caster pass.

In those two functions you get the chance to call set\+Property to set your own variables and add your own pieces.

Another option is to overload Hlms\+::calculate\+Hash\+For which gives you more control but you\textquotesingle{}ll have to do some of the work the base class does.

For some particularly complex features, the Hlms preprocessor may not be enough, too difficult, or just impossible to implement, and thus you can generate the string from C++ and send it as a piece. The template shader can insert it using @insertpiece.

The function Hlms\+::create\+Shader\+Cache\+Entry is the main responsible for generating the shaders and parsing the template through the Hlms preprocessor. If you overload it, you can ignore pieces, properties; basically override the entire Hlms system and provide the source for the shaders yourself.

\subsection*{Common conventions}

Properties starting with \textquotesingle{}hlms\+\_\+\textquotesingle{} prefix are common to all or most Hlms implementations. i.\+e. \textquotesingle{}hlms\+\_\+skeleton\textquotesingle{} is set to 1 when a skeleton is present and hardware skinning should be performed.

Save properties\textquotesingle{} Id\+Strings (hashed strings) into constant as performance optimizations. Ideally the compiler should detect the constant propagation and this shouldn\textquotesingle{}t be needed, but this often isn\textquotesingle{}t the case.

For mobile, avoid mat4 and do the math yourself. As for 4x3 matrices (i.\+e. skinning), perform the math manually as many G\+L\+E\+S2 drivers have issues compiling valid glsl code.

Properties in underscore\+\_\+case are set from C++; propierties in camel\+Case are set from the template.

Propierties and pieces starting with \textquotesingle{}custom\+\_\+\textquotesingle{} are for user customizations of the template

T\+BD

\subsection*{Disabling a stage}

By default if a template isn\textquotesingle{}t present, the shader stage won\textquotesingle{}t be created. e.\+g. if there is no Geometry\+Shader\+\_\+gs.\+glsl file, no geometry shader will be created. However there are times where you want to use a template but only use this stage in particular scenarios (e.\+g. toggled by a material parameter, disable it for shadow mapping, etc.). In this case, set the property hlms\+\_\+disable\+\_\+stage to non-\/zero from within the template (i.\+e. using @set) . The value of this property is reset to 0 for every stage.

Note that even when disabled, the Hlms template will be fully parsed and dumped to disk; and any modification you perform to the Hlms properties will be carried over to the next stages. Setting hlms\+\_\+disable\+\_\+stage is not an early out or an abort.\hypertarget{hlms_customization}{}\subsubsection{Customization}\label{hlms_customization}
In many cases, users may want to slightly customize the shaders to achieve a particular look, implement a specific feature, or solve a unique problem; without having to rewrite the whole implementation.

Maximum flexibility can be get by directly modifying the original source code. However this isn\textquotesingle{}t modular, making it difficult to merge when the original source code has changed. Most of of the customizations don\textquotesingle{}t require such intrusive approach.

Note\+: For performance reasons, the listener interface does not allow you to add customizations that work per Renderable, as that loop is performance sensitive. The only listener callback that works inside Hlms\+::fill\+Buffers\+For is hlms\+Type\+Changed which only gets evaluated when the previous Renderable used a different Hlms implementation; which is rare, and since we sort the Render\+Queue, it often branch predicts well.

There are different levels in which an Hlms implementation can be customized\+:


\begin{DoxyEnumerate}
\item Using a library, see \href{#toc574}{\tt {\itshape Hlms Initialization}}. pass a set of piece files in a folder by pushing the folder to Archive\+Vec. The files in that folder will be parsed first, in order (archive\+Vec\mbox{[}0\mbox{]} then archive\+Vec\mbox{[}1\mbox{]}, … archive\+Vec\mbox{[}N-\/1\mbox{]}); which will let you define your own pieces to insert code into the default template (see the the table at the end). You can also do clever tricky things to avoid dealing with C++ code at all even if there are no \textquotesingle{}custom\+\_\+\textquotesingle{} pieces for it. For example, you can write the following code to override the B\+R\+DF declarations and provide a custom B\+R\+DF\+: 
\begin{DoxyCode}
\textcolor{comment}{//Disable all known BRDFs that the implementation may enable}

@pset( BRDF\_CookTorrance, 0 )

@pset( BRDF\_Default, 0 )

@piece( DeclareBRDF )

\textcolor{comment}{// Your BRDF code declaration here}

\textcolor{keyword}{@end}
\end{DoxyCode}

\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item Via listener, through Hlms\+Listener. This allows you to have access to the buffer pass to fill extra information; or bind extra buffers to the shader.
\item Overload Hlms\+Pbs. Useful for overriding only specific parts, or adding new functionality that requires storing extra information in a datablock (e.\+g. overload Hlms\+Pbs\+Datablock to add more variables, and then overload Hlms\+Pbs\+::create\+Datablock\+Impl to create these custom datablocks)
\item Directly modify Hlms\+Pbs, Hlms\+Pbs\+Datablock and the template. \tabulinesep=1mm
\begin{longtabu} spread 0pt [c]{*{2}{|X[-1]}|}
\hline
\rowcolor{\tableheadbgcolor}\textbf{ Variable }&\textbf{ Description  }\\\cline{1-2}
\endfirsthead
\hline
\endfoot
\hline
\rowcolor{\tableheadbgcolor}\textbf{ Variable }&\textbf{ Description  }\\\cline{1-2}
\endhead
custom\+\_\+pass\+Buffer &Piece where users can add extra information for the pass buffer (only useful if the user is using Hlms\+Listener or overloaded Hlms\+Pbs. \\\cline{1-2}
custom\+\_\+\+V\+Sto\+PS &Piece where users can add more interpolants for passing data from the vertex to the pixel shader. \\\cline{1-2}
custom\+\_\+vs\+\_\+attributes &Custom vertex shader attributes in the Vertex Shader (i.\+e. a special texcoord, etc). \\\cline{1-2}
custom\+\_\+vs\+\_\+uniform\+Declaration &Data declaration (textures, texture buffers, uniform buffers) in the Vertex Shader. \\\cline{1-2}
custom\+\_\+vs\+\_\+pre\+Execution &Executed before \hyperlink{namespace_ogre}{Ogre}\textquotesingle{}s code from the Vertex Shader. \\\cline{1-2}
custom\+\_\+vs\+\_\+pos\+Execution &Executed after all code from the Vertex Shader has been performed. \\\cline{1-2}
custom\+\_\+ps\+\_\+uniform\+Declaration &Same as custom\+\_\+vs\+\_\+uniform\+Declaration, but for the Pixel Shader \\\cline{1-2}
custom\+\_\+ps\+\_\+pre\+Execution &Executed before \hyperlink{namespace_ogre}{Ogre}\textquotesingle{}s code from the Pixel Shader. \\\cline{1-2}
custom\+\_\+ps\+\_\+pos\+Material\+Load &Executed right after loading material data; and before anything else. May not get executed if there is no relevant material data (i.\+e. doesn\textquotesingle{}t have normals or Q\+Tangents for lighting calculation) \\\cline{1-2}
custom\+\_\+ps\+\_\+pre\+Lights &Executed right before any light (i.\+e. to perform your own ambient / global illumination pass). All relevant texture data should be loaded by now. \\\cline{1-2}
custom\+\_\+ps\+\_\+pos\+Execution &Executed after all code from the Pixel Shader has been performed. \\\cline{1-2}
\end{longtabu}

\end{DoxyEnumerate}\hypertarget{Mesh-Tools}{}\section{Mesh Tools}\label{Mesh-Tools}
There are a number of mesh tools available with O\+G\+RE to help you manipulate your meshes.


\begin{DoxyDescription}
\item[\hyperlink{_mesh-_tools_Exporters}{Exporters} ]

For getting data out of modellers and into O\+G\+RE.


\item[\href{#XMLConverter}{\tt X\+M\+L\+Converter} ]

For converting meshes and skeletons to/from X\+ML.


\item[\href{#MeshUpgrader}{\tt Mesh\+Upgrader} ]

For upgrading binary meshes from one version of O\+G\+RE to another.


\end{DoxyDescription}\hypertarget{_mesh-_tools_Exporters}{}\subsection{Exporters}\label{_mesh-_tools_Exporters}
Exporters are plugins to 3D modelling tools which write meshes and skeletal animation to file formats which O\+G\+RE can use for realtime rendering. The files the exporters write end in .mesh and .skeleton respectively.

Each exporter has to be written specifically for the modeller in question, although they all use a common set of facilities provided by the classes Mesh\+Serializer and Skeleton\+Serializer. They also normally require you to own the modelling tool.

All the exporters here can be built from the source code, or you can download precompiled versions from the O\+G\+RE web site.

\section*{A Note About Modelling / Animation For O\+G\+RE}

There are a few rules when creating an animated model for O\+G\+RE\+:


\begin{DoxyItemize}
\item You must have no more than 4 weighted bone assignments per vertex. If you have more, O\+G\+RE will eliminate the lowest weighted assignments and re-\/normalise the other weights. This limit is imposed by hardware blending limitations.
\item All vertices must be assigned to at least one bone -\/ assign static vertices to the root bone.
\item At the very least each bone must have a keyframe at the beginning and end of the animation.
\end{DoxyItemize}

If you’re creating non-\/animated meshes, then you do not need to be concerned with the above.

Full documentation for each exporter is provided along with the exporter itself, and there is a list of the currently supported modelling tools in the O\+G\+RE Wiki at \href{http://www.ogre3d.org/tikiwiki/tiki-index.php?page=OGRE+Exporters&structure=Tools}{\tt http\+://www.\+ogre3d.\+org/tikiwiki/tiki-\/index.\+php?page=\+O\+G\+R\+E+\+Exporters\&structure=\+Tools}.\hypertarget{_mesh-_tools_XMLConverter}{}\subsection{X\+M\+L\+Converter}\label{_mesh-_tools_XMLConverter}
The Ogre\+X\+M\+L\+Converter tool can converter binary .mesh and .skeleton files to X\+ML and back again -\/ this is a very useful tool for debugging the contents of meshes, or for exchanging mesh data easily -\/ many of the modeller mesh exporters export to X\+ML because it is simpler to do, and Ogre\+X\+M\+L\+Converter can then produce a binary from it. Other than simplicity, the other advantage is that Ogre\+X\+M\+L\+Converter can generate additional information for the mesh, like bounding regions and level-\/of-\/detail reduction.

Syntax\+:


\begin{DoxyCode}
Usage: OgreXMLConverter sourcefile [destfile]
sourcefile = name of file to convert
destfile   = optional name of file to write to. If you don't
             specify this OGRE works it out through the extension
             and the XML contents if the source is XML. For example
             test.mesh becomes test.xml, test.xml becomes test.mesh
             if the XML document root is <mesh> etc.
\end{DoxyCode}


When converting X\+ML to .mesh, you will be prompted to (re)generate level-\/of-\/detail(L\+OD) information for the mesh -\/ you can choose to skip this part if you wish, but doing it will allow you to make your mesh reduce in detail automatically when it is loaded into the engine. The engine uses a complex algorithm to determine the best parts of the mesh to reduce in detail depending on many factors such as the curvature of the surface, the edges of the mesh and seams at the edges of textures and smoothing groups -\/ taking advantage of it is advised to make your meshes more scalable in real scenes.\hypertarget{_mesh-_tools_MeshUpgrader}{}\subsection{Mesh\+Upgrader}\label{_mesh-_tools_MeshUpgrader}
This tool is provided to allow you to upgrade your meshes when the binary format changes -\/ sometimes we alter it to add new features and as such you need to keep your own assets up to date. This tools has a very simple syntax\+:


\begin{DoxyCode}
OgreMeshUpgrader <oldmesh> <newmesh>
\end{DoxyCode}


The O\+G\+RE release notes will notify you when this is necessary with a new release. \hypertarget{Hardware-Buffers}{}\section{Hardware Buffers}\label{Hardware-Buffers}
Vertex buffers, index buffers and pixel buffers inherit most of their features from the Hardware\+Buffer class. The general premise with a hardware buffer is that it is an area of memory with which you can do whatever you like; there is no format (vertex or otherwise) associated with the buffer itself -\/ that is entirely up to interpretation by the methods that use it -\/ in that way, a Hardware\+Buffer is just like an area of memory you might allocate using ’malloc’ -\/ the difference being that this memory is likely to be located in G\+PU or A\+GP memory.

\label{_The-Hardware-Buffer-Manager}%
 \label{_The-Hardware-Buffer-Manager-1}%


\section*{The Hardware Buffer Manager}

The Hardware\+Buffer\+Manager class is the factory hub of all the objects in the new geometry system. You create and destroy the majority of the objects you use to define geometry through this class. It’s a Singleton, so you access it by doing Hardware\+Buffer\+Manager\+::get\+Singleton() -\/ however be aware that it is only guaranteed to exist after the Render\+System has been initialised (after you call Root\+::initialise); this is because the objects created are invariably A\+P\+I-\/specific, although you will deal with them through one common interface. For example\+:


\begin{DoxyCode}
\hyperlink{class_ogre_1_1_vertex_declaration}{Ogre::VertexDeclaration}* decl = HardwareBufferManager::getSingleton().
      createVertexDeclaration();
\end{DoxyCode}



\begin{DoxyCode}
\hyperlink{class_ogre_1_1_shared_ptr}{Ogre::HardwareVertexBufferSharedPtr} vbuf = 
    \hyperlink{class_ogre_1_1_hardware_buffer_manager_a380063fef4a4563c90d45a03ac196dc7}{Ogre::HardwareBufferManager::getSingleton}().
      \hyperlink{class_ogre_1_1_hardware_buffer_manager_base_a6009815139b407d20347dd3e2262e5ad}{createVertexBuffer}(
        3*\textcolor{keyword}{sizeof}(\hyperlink{namespace_ogre_aa3a7b6dfb905e6572d62f0dfa3d4274d}{Real}), \textcolor{comment}{// size of one whole vertex}
        numVertices, \textcolor{comment}{// number of vertices}
        \hyperlink{class_ogre_1_1_hardware_buffer_ae51f5970d879af736e4cf53e1ec46630a5ffbb339becd31435c5f616be4c28996}{Ogre::HardwareBuffer::HBU\_STATIC\_WRITE\_ONLY}, \textcolor{comment}{// usage}
        \textcolor{keyword}{false}); \textcolor{comment}{// no shadow buffer}
\end{DoxyCode}


Don’t worry about the details of the above, we’ll cover that in the later sections. The important thing to remember is to always create objects through the Hardware\+Buffer\+Manager, don’t use ’new’ (it won’t work anyway in most cases).\hypertarget{_hardware-_buffers_Buffer-Usage}{}\subsection{Buffer Usage}\label{_hardware-_buffers_Buffer-Usage}
Because the memory in a hardware buffer is likely to be under significant contention during the rendering of a scene, the kind of access you need to the buffer over the time it is used is extremely important; whether you need to update the contents of the buffer regularly, whether you need to be able to read information back from it, these are all important factors to how the graphics card manages the buffer. The method and exact parameters used to create a buffer depends on whether you are creating an index or vertex buffer (See \href{#Hardware-Vertex-Buffers}{\tt Hardware Vertex Buffers} and See \href{#Hardware-Index-Buffers}{\tt Hardware Index Buffers}), however one creation parameter is common to them both -\/ the ’usage’. The most optimal type of hardware buffer is one which is not updated often, and is never read from. The usage parameter of create\+Vertex\+Buffer or create\+Index\+Buffer can be one of \hyperlink{class_ogre_1_1_hardware_buffer_ae51f5970d879af736e4cf53e1ec46630}{Ogre\+::\+Hardware\+Buffer\+::\+Usage}.

Choosing the usage of your buffers carefully is important to getting optimal performance out of your geometry. If you have a situation where you need to update a vertex buffer often, consider whether you actually need to update {\bfseries all} the parts of it, or just some. If it’s the latter, consider using more than one buffer, with only the data you need to modify in the H\+B\+U\+\_\+\+D\+Y\+N\+A\+M\+IC buffer. Always try to use the \+\_\+\+W\+R\+I\+T\+E\+\_\+\+O\+N\+LY forms. This just means that you cannot read {\itshape directly} from the hardware buffer, which is good practice because reading from hardware buffers is very slow. If you really need to read data back, use a shadow buffer, described in the next section.\hypertarget{_hardware-_buffers_Shadow-Buffers}{}\subsubsection{Shadow Buffers}\label{_hardware-_buffers_Shadow-Buffers}
As discussed in the previous section, reading data back from a hardware buffer performs very badly. However, if you have a cast-\/iron need to read the contents of the vertex buffer, you should set the ’shadow\+Buffer’ parameter of create\+Vertex\+Buffer or create\+Index\+Buffer to ’true’. This causes the hardware buffer to be backed with a system memory copy, which you can read from with no more penalty than reading ordinary memory. The catch is that when you write data into this buffer, it will first update the system memory copy, then it will update the hardware buffer, as separate copying process -\/ therefore this technique has an additional overhead when writing data. Don’t use it unless you really need it.\hypertarget{_hardware-_buffers_Locking-buffers}{}\subsubsection{Locking buffers}\label{_hardware-_buffers_Locking-buffers}
In order to read or update a hardware buffer, you have to ’lock’ it. This performs 2 functions -\/ it tells the card that you want access to the buffer (which can have an effect on its rendering queue), and it returns a pointer which you can manipulate. Note that if you’ve asked to read the buffer (and remember, you really shouldn’t unless you’ve set the buffer up with a shadow buffer), the contents of the hardware buffer will have been copied into system memory somewhere in order for you to get access to it. For the same reason, when you’re finished with the buffer you must unlock it; if you locked the buffer for writing this will trigger the process of uploading the modified information to the graphics hardware.

\label{_Lock-parameters}%


\subsubsection*{Lock parameters}

When you lock a buffer, you call one of the following methods\+:


\begin{DoxyCode}
\textcolor{comment}{// Lock the entire buffer}
pBuffer->lock(lockType);
\textcolor{comment}{// Lock only part of the buffer}
pBuffer->lock(start, length, lockType);
\end{DoxyCode}


The first call locks the entire buffer, the second locks only the section from ’start’ (as a byte offset), for ’length’ bytes. This could be faster than locking the entire buffer since less is transferred, but not if you later update the rest of the buffer too, because doing it in small chunks like this means you cannot use \hyperlink{class_ogre_1_1_hardware_buffer_aac34930556f611928ec9157c04bd1b0fa176ad39ac15fc0a6028d820a6fe228ae}{Ogre\+::\+Hardware\+Buffer\+::\+H\+B\+L\+\_\+\+D\+I\+S\+C\+A\+RD}. The lock\+Type parameter can have a large effect on the performance of your application, especially if you are not using a shadow buffer. See \hyperlink{class_ogre_1_1_hardware_buffer_aac34930556f611928ec9157c04bd1b0f}{Ogre\+::\+Hardware\+Buffer\+::\+Lock\+Options}.

Once you have locked a buffer, you can use the pointer returned however you wish (just don’t bother trying to read the data that’s there if you’ve used H\+B\+L\+\_\+\+D\+I\+S\+C\+A\+RD, or write the data if you’ve used H\+B\+L\+\_\+\+R\+E\+A\+D\+\_\+\+O\+N\+LY). Modifying the contents depends on the type of buffer, See \href{#Hardware-Vertex-Buffers}{\tt Hardware Vertex Buffers} and See \href{#Hardware-Index-Buffers}{\tt Hardware Index Buffers}\hypertarget{_hardware-_buffers_Practical-Buffer-Tips}{}\subsubsection{Practical Buffer Tips}\label{_hardware-_buffers_Practical-Buffer-Tips}
The interplay of usage mode on creation, and locking options when reading / updating is important for performance. Here’s some tips\+:


\begin{DoxyEnumerate}
\item Aim for the ’perfect’ buffer by creating with H\+B\+U\+\_\+\+S\+T\+A\+T\+I\+C\+\_\+\+W\+R\+I\+T\+E\+\_\+\+O\+N\+LY, with no shadow buffer, and locking all of it once only with H\+B\+L\+\_\+\+D\+I\+S\+C\+A\+RD to populate it. Never touch it again.
\item If you need to update a buffer regularly, you will have to compromise. Use H\+B\+U\+\_\+\+D\+Y\+N\+A\+M\+I\+C\+\_\+\+W\+R\+I\+T\+E\+\_\+\+O\+N\+LY when creating (still no shadow buffer), and use H\+B\+L\+\_\+\+D\+I\+S\+C\+A\+RD to lock the entire buffer, or if you can’t then use H\+B\+L\+\_\+\+N\+O\+\_\+\+O\+V\+E\+R\+W\+R\+I\+TE to lock parts of it.
\item If you really need to read data from the buffer, create it with a shadow buffer. Make sure you use H\+B\+L\+\_\+\+R\+E\+A\+D\+\_\+\+O\+N\+LY when locking for reading because it will avoid the upload normally associated with unlocking the buffer. You can also combine this with either of the 2 previous points, obviously try for static if you can -\/ remember that the \+\_\+\+W\+R\+I\+T\+E\+\_\+\+O\+N\+L\+Y’ part refers to the hardware buffer so can be safely used with a shadow buffer you read from.
\item Split your vertex buffers up if you find that your usage patterns for different elements of the vertex are different. No point having one huge updatable buffer with all the vertex data in it, if all you need to update is the texture coordinates. Split that part out into it’s own buffer and make the rest H\+B\+U\+\_\+\+S\+T\+A\+T\+I\+C\+\_\+\+W\+R\+I\+T\+E\+\_\+\+O\+N\+LY.
\end{DoxyEnumerate}\hypertarget{_hardware-_buffers_Hardware-Vertex-Buffers}{}\subsection{Hardware Vertex Buffers}\label{_hardware-_buffers_Hardware-Vertex-Buffers}
This section covers specialised hardware buffers which contain vertex data. For a general discussion of hardware buffers, along with the rules for creating and locking them, see the \href{#Hardware-Buffers}{\tt Hardware Buffers} section.\hypertarget{_hardware-_buffers_The-VertexData-class}{}\subsubsection{The Vertex\+Data class}\label{_hardware-_buffers_The-VertexData-class}
The \hyperlink{class_ogre_1_1_vertex_data}{Ogre\+::\+Vertex\+Data} class collects together all the vertex-\/related information used to render geometry. The new Render\+Operation requires a pointer to a Vertex\+Data object, and it is also used in Mesh and Sub\+Mesh to store the vertex positions, normals, texture coordinates etc. Vertex\+Data can either be used alone (in order to render unindexed geometry, where the stream of vertices defines the triangles), or in combination with Index\+Data where the triangles are defined by indexes which refer to the entries in Vertex\+Data. It’s worth noting that you don’t necessarily have to use Vertex\+Data to store your applications geometry; all that is required is that you can build a Vertex\+Data structure when it comes to rendering. This is pretty easy since all of Vertex\+Data’s members are pointers, so you could maintain your vertex buffers and declarations in alternative structures if you like, so long as you can convert them for rendering. The Vertex\+Data class has a number of important members\+:


\begin{DoxyDescription}
\item[vertex\+Start ]

The position in the bound buffers to start reading vertex data from. This allows you to use a single buffer for many different renderables.


\item[vertex\+Count ]

The number of vertices to process in this particular rendering group


\item[vertex\+Declaration ]

A pointer to a Vertex\+Declaration object which defines the format of the vertex input; note this is created for you by Vertex\+Data. See \href{#Vertex-Declarations}{\tt Vertex Declarations}


\item[vertex\+Buffer\+Binding ]

A pointer to a Vertex\+Buffer\+Binding object which defines which vertex buffers are bound to which sources -\/ again, this is created for you by Vertex\+Data. See \href{#Vertex-Buffer-Bindings}{\tt Vertex Buffer Bindings}


\end{DoxyDescription}\hypertarget{_hardware-_buffers_Vertex-Declarations}{}\subsubsection{Vertex Declarations}\label{_hardware-_buffers_Vertex-Declarations}
Vertex declarations define the vertex inputs used to render the geometry you want to appear on the screen. Basically this means that for each vertex, you want to feed a certain set of data into the graphics pipeline, which (you hope) will affect how it all looks when the triangles are drawn. Vertex declarations let you pull items of data (which we call vertex elements, represented by the Vertex\+Element class) from any number of buffers, both shared and dedicated to that particular element. It’s your job to ensure that the contents of the buffers make sense when interpreted in the way that your Vertex\+Declaration indicates that they should. To add an element to a Vertex\+Declaration, you call \hyperlink{class_ogre_1_1_vertex_declaration_a8b1a5f5fe0b7306da4c8b17357d45fac}{Ogre\+::\+Vertex\+Declaration\+::add\+Element} method. The parameters to this method are\+:


\begin{DoxyDescription}
\item[source ]

This tells the declaration which buffer the element is to be pulled from. Note that this is just an index, which may range from 0 to one less than the number of buffers which are being bound as sources of vertex data. See \href{#Vertex-Buffer-Bindings}{\tt Vertex Buffer Bindings} for information on how a real buffer is bound to a source index. Storing the source of the vertex element this way (rather than using a buffer pointer) allows you to rebind the source of a vertex very easily, without changing the declaration of the vertex format itself.


\item[offset ]

Tells the declaration how far in bytes the element is offset from the start of each whole vertex in this buffer. This will be 0 if this is the only element being sourced from this buffer, but if other elements are there then it may be higher. A good way of thinking of this is the size of all vertex elements which precede this element in the buffer.


\item[type ]

This defines the data type of the vertex input, including it’s size. This is an important element because as G\+P\+Us become more advanced, we can no longer assume that position input will always require 3 floating point numbers, because programmable vertex pipelines allow full control over the inputs and outputs. This part of the element definition covers the basic type and size, e.\+g. V\+E\+T\+\_\+\+F\+L\+O\+A\+T3 is 3 floating point numbers -\/ the meaning of the data is dealt with in the next parameter.


\item[semantic ]

This defines the meaning of the element -\/ the G\+PU will use this to determine what to use this input for, and programmable vertex pipelines will use this to identify which semantic to map the input to. This can identify the element as positional data, normal data, texture coordinate data, etc. See the A\+PI reference for full details of all the options.


\item[index ]

This parameter is only required when you supply more than one element of the same semantic in one vertex declaration. For example, if you supply more than one set of texture coordinates, you would set first sets index to 0, and the second set to 1.


\end{DoxyDescription}

You can repeat the call to add\+Element for as many elements as you have in your vertex input structures. There are also useful methods on Vertex\+Declaration for locating elements within a declaration -\/ see the A\+PI reference for full details.\hypertarget{_hardware-_buffers_Important-Considerations}{}\subsubsection{Important Considerations}\label{_hardware-_buffers_Important-Considerations}
Whilst in theory you have completely full reign over the format of you vertices, in reality there are some restrictions. Older DirectX hardware imposes a fixed ordering on the elements which are pulled from each buffer; specifically any hardware prior to DirectX 9 may impose the following restrictions\+:


\begin{DoxyItemize}
\item Vertex\+Elements should be added in the following order, and the order of the elements within any shared buffer should be as follows\+:
\begin{DoxyEnumerate}
\item Positions
\item Blending weights
\item Normals
\item Diffuse colours
\item Specular colours
\item Texture coordinates (starting at 0, listed in order, with no gaps)
\end{DoxyEnumerate}
\item You must not have unused gaps in your buffers which are not referenced by any Vertex\+Element
\item You must not cause the buffer \& offset settings of 2 Vertex\+Elements to overlap
\end{DoxyItemize}

Open\+GL and DirectX 9 compatible hardware are not required to follow these strict limitations, so you might find, for example that if you broke these rules your application would run under Open\+GL and under DirectX on recent cards, but it is not guaranteed to run on older hardware under DirectX unless you stick to the above rules. For this reason you’re advised to abide by them!\hypertarget{_hardware-_buffers_Vertex-Buffer-Bindings}{}\subsubsection{Vertex Buffer Bindings}\label{_hardware-_buffers_Vertex-Buffer-Bindings}
Vertex buffer bindings are about associating a vertex buffer with a source index used in \href{#Vertex-Declarations}{\tt Vertex Declarations}.\hypertarget{_hardware-_buffers_Creating-the-Vertex-Buffer}{}\subsubsection{Creating the Vertex Buffer}\label{_hardware-_buffers_Creating-the-Vertex-Buffer}
Firstly, lets look at how you create a vertex buffer\+:


\begin{DoxyCode}
\hyperlink{namespace_ogre_a05ef9b65d4ed446b994636e371bf5aab}{HardwareVertexBufferSharedPtr} vbuf = 
    \hyperlink{class_ogre_1_1_hardware_buffer_manager_a380063fef4a4563c90d45a03ac196dc7}{Ogre::HardwareBufferManager::getSingleton}().
      \hyperlink{class_ogre_1_1_hardware_buffer_manager_base_a6009815139b407d20347dd3e2262e5ad}{createVertexBuffer}(
        3*\textcolor{keyword}{sizeof}(\hyperlink{namespace_ogre_aa3a7b6dfb905e6572d62f0dfa3d4274d}{Real}), \textcolor{comment}{// size of one whole vertex}
        numVertices, \textcolor{comment}{// number of vertices}
        HardwareBuffer::HBU\_STATIC\_WRITE\_ONLY, \textcolor{comment}{// usage}
        \textcolor{keyword}{false}); \textcolor{comment}{// no shadow buffer}
\end{DoxyCode}


Notice that we use \href{#The-Hardware-Buffer-Manager}{\tt The Hardware Buffer Manager} to create our vertex buffer, and that a class called Hardware\+Vertex\+Buffer\+Shared\+Ptr is returned from the method, rather than a raw pointer. This is because vertex buffers are reference counted -\/ you are able to use a single vertex buffer as a source for multiple pieces of geometry therefore a standard pointer would not be good enough, because you would not know when all the different users of it had finished with it. The Hardware\+Vertex\+Buffer\+Shared\+Ptr class manages its own destruction by keeping a reference count of the number of times it is being used -\/ when the last Hardware\+Vertex\+Buffer\+Shared\+Ptr is destroyed, the buffer itself automatically destroys itself.

The parameters to the creation of a vertex buffer are as follows\+:


\begin{DoxyDescription}
\item[vertex\+Size ]

The size in bytes of a whole vertex in this buffer. A vertex may include multiple elements, and in fact the contents of the vertex data may be reinterpreted by different vertex declarations if you wish. Therefore you must tell the buffer manager how large a whole vertex is, but not the internal format of the vertex, since that is down to the declaration to interpret. In the above example, the size is set to the size of 3 floating point values -\/ this would be enough to hold a standard 3D position or normal, or a 3D texture coordinate, per vertex.


\item[num\+Vertices ]

The number of vertices in this buffer. Remember, not all the vertices have to be used at once -\/ it can be beneficial to create large buffers which are shared between many chunks of geometry because changing vertex buffer bindings is a render state switch, and those are best minimised.


\item[usage ]

This tells the system how you intend to use the buffer. See \href{#Buffer-Usage}{\tt Buffer Usage}


\item[use\+Shadow\+Buffer ]

Tells the system whether you want this buffer backed by a system-\/memory copy. See \href{#Shadow-Buffers}{\tt Shadow Buffers}


\end{DoxyDescription}\hypertarget{_hardware-_buffers_Binding-the-Vertex-Buffer}{}\subsubsection{Binding the Vertex Buffer}\label{_hardware-_buffers_Binding-the-Vertex-Buffer}
The second part of the process is to bind this buffer which you have created to a source index. To do this, you call\+:


\begin{DoxyCode}
vertexBufferBinding->setBinding(0, vbuf);
\end{DoxyCode}


This results in the vertex buffer you created earlier being bound to source index 0, so any vertex element which is pulling its data from source index 0 will retrieve data from this buffer. There are also methods for retrieving buffers from the binding data -\/ see the A\+PI reference for full details.\hypertarget{_hardware-_buffers_Updating-Vertex-Buffers}{}\subsubsection{Updating Vertex Buffers}\label{_hardware-_buffers_Updating-Vertex-Buffers}
The complexity of updating a vertex buffer entirely depends on how its contents are laid out. You can lock a buffer (See \href{#Locking-buffers}{\tt Locking buffers}), but how you write data into it vert much depends on what it contains. Lets start with a vert simple example. Lets say you have a buffer which only contains vertex positions, so it only contains sets of 3 floating point numbers per vertex. In this case, all you need to do to write data into it is\+:


\begin{DoxyCode}
\hyperlink{namespace_ogre_aa3a7b6dfb905e6572d62f0dfa3d4274d}{Real}* pReal = \textcolor{keyword}{static\_cast<}\hyperlink{namespace_ogre_aa3a7b6dfb905e6572d62f0dfa3d4274d}{Real}*\textcolor{keyword}{>}(vbuf->lock(HardwareBuffer::HBL\_DISCARD));
\end{DoxyCode}


... then you just write positions in chunks of 3 reals. If you have other floating point data in there, it’s a little more complex but the principle is largely the same, you just need to write alternate elements. But what if you have elements of different types, or you need to derive how to write the vertex data from the elements themselves? Well, there are some useful methods on the Vertex\+Element class to help you out. Firstly, you lock the buffer but assign the result to a unsigned char$\ast$ rather than a specific type. Then, for each element which is sourcing from this buffer (which you can find out by calling Vertex\+Declaration\+::find\+Elements\+By\+Source) you call Vertex\+Element\+::base\+Vertex\+Pointer\+To\+Element. This offsets a pointer which points at the base of a vertex in a buffer to the beginning of the element in question, and allows you to use a pointer of the right type to boot. Here’s a full example\+:


\begin{DoxyCode}
\textcolor{comment}{// Get base pointer}
\textcolor{keywordtype}{unsigned} \textcolor{keywordtype}{char}* pVert = \textcolor{keyword}{static\_cast<}\textcolor{keywordtype}{unsigned} \textcolor{keywordtype}{char}*\textcolor{keyword}{>}(vbuf->lock(HardwareBuffer::HBL\_READ\_ONLY));
\hyperlink{namespace_ogre_aa3a7b6dfb905e6572d62f0dfa3d4274d}{Real}* pReal;
\textcolor{keywordflow}{for} (\textcolor{keywordtype}{size\_t} v = 0; v < vertexCount; ++v)
\{
    \textcolor{comment}{// Get elements}
    VertexDeclaration::VertexElementList elems = decl->\hyperlink{class_ogre_1_1_vertex_declaration_ada92fbc9ee87b04f8a3c389c71904ce6}{findElementsBySource}(bufferIdx);
    VertexDeclaration::VertexElementList::iterator i, iend;
    \textcolor{keywordflow}{for} (i = elems.begin(); i != elems.end(); ++i)
    \{
        VertexElement& elem = *i;
        \textcolor{keywordflow}{if} (elem.getSemantic() == \hyperlink{group___render_system_gga0a62b3f2ede8992ff365bb013a8bc00dad04d50e91c2ec5377e610b3f5b9b07f2}{VES\_POSITION})
        \{
            elem.baseVertexPointerToElement(pVert, &pReal);
            \textcolor{comment}{// write position using pReal}

        \}

        ...


    \}
    pVert += vbuf->getVertexSize();
\}
vbuf->unlock();
\end{DoxyCode}


See the A\+PI docs for full details of all the helper methods on Vertex\+Declaration and Vertex\+Element to assist you in manipulating vertex buffer data pointers.\hypertarget{_hardware-_buffers_Hardware-Index-Buffers}{}\subsection{Hardware Index Buffers}\label{_hardware-_buffers_Hardware-Index-Buffers}
Index buffers are used to render geometry by building triangles out of vertices indirectly by reference to their position in the buffer, rather than just building triangles by sequentially reading vertices. Index buffers are simpler than vertex buffers, since they are just a list of indexes at the end of the day, however they can be held on the hardware and shared between multiple pieces of geometry in the same way vertex buffers can, so the rules on creation and locking are the same. See \href{#Hardware-Buffers}{\tt Hardware Buffers} for information.\hypertarget{_hardware-_buffers_The-IndexData-class}{}\subsubsection{The Index\+Data class}\label{_hardware-_buffers_The-IndexData-class}
This class summarises the information required to use a set of indexes to render geometry. It’s members are as follows\+:


\begin{DoxyDescription}
\item[index\+Start ]

The first index used by this piece of geometry; this can be useful for sharing a single index buffer among several geometry pieces.


\item[index\+Count ]

The number of indexes used by this particular renderable.


\item[index\+Buffer ]

The index buffer which is used to source the indexes.


\end{DoxyDescription}\label{_Creating-an-Index-Buffer}%


\subsection*{Creating an Index Buffer}

Index buffers are created using See \href{#The-Hardware-Buffer-Manager}{\tt The Hardware Buffer Manager} just like vertex buffers, here’s how\+:


\begin{DoxyCode}
\hyperlink{namespace_ogre_ae906cf8e579ba8ade19879ec05b1a456}{HardwareIndexBufferSharedPtr} ibuf = 
      \hyperlink{class_ogre_1_1_hardware_buffer_manager_a380063fef4a4563c90d45a03ac196dc7}{Ogre::HardwareBufferManager::getSingleton}().
    createIndexBuffer(
        HardwareIndexBuffer::IT\_16BIT, \textcolor{comment}{// type of index}
        numIndexes, \textcolor{comment}{// number of indexes}
        HardwareBuffer::HBU\_STATIC\_WRITE\_ONLY, \textcolor{comment}{// usage}
        \textcolor{keyword}{false}); \textcolor{comment}{// no shadow buffer }
\end{DoxyCode}


Once again, notice that the return type is a class rather than a pointer; this is reference counted so that the buffer is automatically destroyed when no more references are made to it. The parameters to the index buffer creation are\+:


\begin{DoxyDescription}
\item[index\+Type ]

There are 2 types of index; 16-\/bit and 32-\/bit. They both perform the same way, except that the latter can address larger vertex buffers. If your buffer includes more than 65526 vertices, then you will need to use 32-\/bit indexes. Note that you should only use 32-\/bit indexes when you need to, since they incur more overhead than 16-\/bit vertices, and are not supported on some older hardware.


\item[num\+Indexes ]

The number of indexes in the buffer. As with vertex buffers, you should consider whether you can use a shared index buffer which is used by multiple pieces of geometry, since there can be performance advantages to switching index buffers less often.


\item[usage ]

This tells the system how you intend to use the buffer. See \href{#Buffer-Usage}{\tt Buffer Usage}


\item[use\+Shadow\+Buffer ]

Tells the system whether you want this buffer backed by a system-\/memory copy. See \href{#Shadow-Buffers}{\tt Shadow Buffers}


\end{DoxyDescription}\hypertarget{_hardware-_buffers_Updating-Index-Buffers}{}\subsubsection{Updating Index Buffers}\label{_hardware-_buffers_Updating-Index-Buffers}
Updating index buffers can only be done when you lock the buffer for writing; See \href{#Locking-buffers}{\tt Locking buffers} for details. Locking returns a void pointer, which must be cast to the appropriate type; with index buffers this is either an unsigned short (for 16-\/bit indexes) or an unsigned long (for 32-\/bit indexes). For example\+:


\begin{DoxyCode}
\textcolor{keywordtype}{unsigned} \textcolor{keywordtype}{short}* pIdx = \textcolor{keyword}{static\_cast<}\textcolor{keywordtype}{unsigned} \textcolor{keywordtype}{short}*\textcolor{keyword}{>}(ibuf->lock(HardwareBuffer::HBL\_DISCARD));
\end{DoxyCode}


You can then write to the buffer using the usual pointer semantics, just remember to unlock the buffer when you’re finished!\hypertarget{_hardware-_buffers_Hardware-Pixel-Buffers}{}\subsection{Hardware Pixel Buffers}\label{_hardware-_buffers_Hardware-Pixel-Buffers}
Hardware Pixel Buffers are a special kind of buffer that stores graphical data in graphics card memory, generally for use as textures. Pixel buffers can represent a one dimensional, two dimensional or three dimensional image. A texture can consist of a multiple of these buffers.

In contrary to vertex and index buffers, pixel buffers are not constructed directly. When creating a texture, the necessary pixel buffers to hold its data are constructed automatically.\hypertarget{_hardware-_buffers_Textures}{}\subsubsection{Textures}\label{_hardware-_buffers_Textures}
A texture is an image that can be applied onto the surface of a three dimensional model. In \hyperlink{namespace_ogre}{Ogre}, textures are represented by the Texture resource class.\hypertarget{_hardware-_buffers_Creating-a-texture}{}\paragraph{Creating a texture}\label{_hardware-_buffers_Creating-a-texture}
Textures are created through the Texture\+Manager. In most cases they are created from image files directly by the \hyperlink{namespace_ogre}{Ogre} resource system. If you are reading this, you most probably want to create a texture manually so that you can provide it with image data yourself. This is done through Texture\+Manager\+::create\+Manual\+:


\begin{DoxyCode}
ptex = \hyperlink{class_ogre_1_1_texture_manager_ac6fb858ee86f3b7b75de32e3e04ee5c8}{Ogre::TextureManager::getSingleton}().
      \hyperlink{class_ogre_1_1_texture_manager_aafa494d2704fdff05708db9db4bac3a0}{createManual}(
    \textcolor{stringliteral}{"MyManualTexture"}, \textcolor{comment}{// Name of texture}
    \textcolor{stringliteral}{"General"}, \textcolor{comment}{// Name of resource group in which the texture should be created}
    \hyperlink{group___resources_ggae50520af6377ff8184cf79125cb9c4d7af1f732018f5a2a7d35233e2ceeb4ee0e}{Ogre::TEX\_TYPE\_2D}, \textcolor{comment}{// Texture type}
    256, \textcolor{comment}{// Width}
    256, \textcolor{comment}{// Height}
    1, \textcolor{comment}{// Depth (Must be 1 for two dimensional textures)}
    0, \textcolor{comment}{// No mipmaps}
    \hyperlink{group___image_gga7e0353e7d36d4c2e8468641b7303d39ca0d5c9bdb0633c1849758fea566a2b754}{PF\_A8R8G8B8}, \textcolor{comment}{// internal Pixel format}
    \hyperlink{group___resources_ggaf140ec886884a864abc74a7556f8bf67ac26eda030d21e0491461edea89394493}{Ogre::TU\_DYNAMIC\_WRITE\_ONLY} \textcolor{comment}{// usage}
);
\end{DoxyCode}


This example creates a texture named {\itshape My\+Manual\+Texture} in resource group {\itshape General}. It is a square {\itshape two dimensional} texture, with width 256 and height 256.

The different texture types will be discussed in \hyperlink{group___resources_gae50520af6377ff8184cf79125cb9c4d7}{Ogre\+::\+Texture\+Type}. Pixel formats are summarised in \href{#Pixel-Formats}{\tt Pixel Formats}.

In addition to the hardware buffer usages as described in \hyperlink{class_ogre_1_1_hardware_buffer_ae51f5970d879af736e4cf53e1ec46630}{Ogre\+::\+Hardware\+Buffer\+::\+Usage} there are some usage flags specific to textures\+: \hyperlink{group___resources_gaf140ec886884a864abc74a7556f8bf67}{Ogre\+::\+Texture\+Usage}.\hypertarget{_hardware-_buffers_Getting-a-PixelBuffer}{}\subsubsection{Getting a Pixel\+Buffer}\label{_hardware-_buffers_Getting-a-PixelBuffer}
A Texture can consist of multiple Pixel\+Buffers, one for each combo if mipmap level and face number. To get a Pixel\+Buffer from a Texture object the method Texture\+::get\+Buffer(face, mipmap) is used\+:

{\itshape face} should be zero for non-\/cubemap textures. For cubemap textures it identifies the face to use, which is one of the cube faces described in See \href{#Texture-Types}{\tt Texture Types}.

{\itshape mipmap} is zero for the zeroth mipmap level, one for the first mipmap level, and so on. On textures that have automatic mipmap generation (T\+U\+\_\+\+A\+U\+T\+O\+M\+I\+P\+M\+AP) only level 0 should be accessed, the rest will be taken care of by the rendering A\+PI.

A simple example of using get\+Buffer is


\begin{DoxyCode}
\textcolor{comment}{// Get the PixelBuffer for face 0, mipmap 0.}
\hyperlink{namespace_ogre_a7786bdc8f60fd946ec3e5ff896276bcf}{HardwarePixelBufferSharedPtr} ptr = tex->getBuffer(0,0);
\end{DoxyCode}
\hypertarget{_hardware-_buffers_Updating-Pixel-Buffers}{}\subsubsection{Updating Pixel Buffers}\label{_hardware-_buffers_Updating-Pixel-Buffers}
Pixel Buffers can be updated in two different ways; a simple, convenient way and a more difficult (but in some cases faster) method. Both methods make use of \hyperlink{class_ogre_1_1_pixel_box}{Ogre\+::\+Pixel\+Box} objects to represent image data in memory.\hypertarget{_hardware-_buffers_blitFromMemory}{}\subsubsection{Blit from memory}\label{_hardware-_buffers_blitFromMemory}
The easy method to get an image into a Pixel\+Buffer is by using Hardware\+Pixel\+Buffer\+::blit\+From\+Memory. This takes a Pixel\+Box object and does all necessary pixel format conversion and scaling for you. For example, to create a manual texture and load an image into it, all you have to do is


\begin{DoxyCode}
\textcolor{comment}{// Manually loads an image and puts the contents in a manually created texture}
\hyperlink{class_ogre_1_1_image}{Ogre::Image} img;
img.\hyperlink{class_ogre_1_1_image_a75ced161976ffbb4fc1cf63d4b007993}{load}(\textcolor{stringliteral}{"elephant.png"}, \textcolor{stringliteral}{"General"});
\textcolor{comment}{// Create RGB texture with 5 mipmaps}
\hyperlink{namespace_ogre_aa381890787803da43b614dee8d9c8994}{TexturePtr} tex = \hyperlink{class_ogre_1_1_texture_manager_ac6fb858ee86f3b7b75de32e3e04ee5c8}{Ogre::TextureManager::getSingleton}().
      \hyperlink{class_ogre_1_1_texture_manager_aafa494d2704fdff05708db9db4bac3a0}{createManual}(
    \textcolor{stringliteral}{"elephant"},
    \textcolor{stringliteral}{"General"},
    \hyperlink{group___resources_ggae50520af6377ff8184cf79125cb9c4d7af1f732018f5a2a7d35233e2ceeb4ee0e}{Ogre::TEX\_TYPE\_2D},
    img.\hyperlink{class_ogre_1_1_image_a649d36eb8288161540d223b7106b7d67}{getWidth}(), img.\hyperlink{class_ogre_1_1_image_a064e61e5225c5405d838e2e96a45beed}{getHeight}(),
    5, \hyperlink{group___image_gga7e0353e7d36d4c2e8468641b7303d39ca2542d39f6712cb6f69907330a31a9342}{Ogre::PF\_X8R8G8B8});
\textcolor{comment}{// Copy face 0 mipmap 0 of the image to face 0 mipmap 0 of the texture.}
tex->\hyperlink{class_ogre_1_1_texture_a5df1d413ab5aab631adc59c9fac06d22}{getBuffer}(0,0)->blitFromMemory(img.\hyperlink{class_ogre_1_1_image_afb8692cfc9e8f50271254722825f6c2b}{getPixelBox}(0,0));
\end{DoxyCode}
\hypertarget{_hardware-_buffers_Direct-memory-locking}{}\subsubsection{Direct memory locking}\label{_hardware-_buffers_Direct-memory-locking}
A more advanced method to transfer image data from and to a Pixel\+Buffer is to use locking. By locking a Pixel\+Buffer you can directly access its contents in whatever the internal format of the buffer inside the G\+PU is.


\begin{DoxyCode}
buffer->lock(HardwareBuffer::HBL\_DISCARD);
\textcolor{keyword}{const} \hyperlink{class_ogre_1_1_pixel_box}{Ogre::PixelBox} &pb = buffer->getCurrentLock();

\hyperlink{namespace_ogre_adf2a0cf2e77143b5ee1d38a75e289545}{uint32} *data = \textcolor{keyword}{static\_cast<}\hyperlink{namespace_ogre_adf2a0cf2e77143b5ee1d38a75e289545}{uint32}*\textcolor{keyword}{>}(pb.\hyperlink{class_ogre_1_1_pixel_box_a59624c7c33ade5365428473a1f3dc85a}{data});
\textcolor{keywordtype}{size\_t} height = pb.\hyperlink{struct_ogre_1_1_box_a352d26dea0069f2e7f1414e8caa2328c}{getHeight}();
\textcolor{keywordtype}{size\_t} width = pb.\hyperlink{struct_ogre_1_1_box_a5499449ff454ff98aaa697f8854376fc}{getWidth}();
\textcolor{keywordtype}{size\_t} pitch = pb.\hyperlink{class_ogre_1_1_pixel_box_aacf8f1ebed40c557389d9d1e9dda3b68}{rowPitch}; \textcolor{comment}{// Skip between rows of image}
\textcolor{keywordflow}{for}(\textcolor{keywordtype}{size\_t} y=0; y<height; ++y)
\{
    \textcolor{keywordflow}{for}(\textcolor{keywordtype}{size\_t} x=0; x<width; ++x)
    \{
        \textcolor{comment}{// 0xRRGGBB -> fill the buffer with yellow pixels}
        data[pitch*y + x] = 0x00FFFF00;
    \}
\}

buffer->unlock();
\end{DoxyCode}
\hypertarget{_hardware-_buffers_Texture-Types}{}\subsubsection{Texture Types}\label{_hardware-_buffers_Texture-Types}
There are several types of textures supported by current hardware (see \hyperlink{group___resources_gae50520af6377ff8184cf79125cb9c4d7}{Ogre\+::\+Texture\+Type}), the first three only differ in the amount of dimensions they have (one, two or three).\hypertarget{_hardware-_buffers_Cube-map-textures}{}\subsubsection{Cube map textures}\label{_hardware-_buffers_Cube-map-textures}
The cube map texture type (\hyperlink{group___resources_ggae50520af6377ff8184cf79125cb9c4d7ae295fe0fa26623b66cc023f462962344}{Ogre\+::\+T\+E\+X\+\_\+\+T\+Y\+P\+E\+\_\+\+C\+U\+B\+E\+\_\+\+M\+AP}) is a different beast from the others; a cube map texture represents a series of six two dimensional images addressed by 3D texture coordinates.


\begin{DoxyDescription}
\item[+X (face 0) ]

Represents the positive x plane (right).


\item[-\/X (face 1) ]

Represents the negative x plane (left).


\item[+Y (face 2) ]

Represents the positive y plane (top).


\item[-\/Y (face 3) ]

Represents the negative y plane (bottom).


\item[+Z (face 4) ]

Represents the positive z plane (front).


\item[-\/Z (face 5) ]

Represents the negative z plane (back).


\end{DoxyDescription}\hypertarget{_hardware-_buffers_Pixel-Formats}{}\subsubsection{Pixel Formats}\label{_hardware-_buffers_Pixel-Formats}
A pixel format described the storage format of pixel data. It defines the way pixels are encoded in memory. The following classes of pixel formats (P\+F\+\_\+$\ast$) are defined\+:


\begin{DoxyDescription}
\item[Native endian formats (P\+F\+\_\+\+A8\+R8\+G8\+B8 and other formats with bit counts) ]

These are native endian (16, 24 and 32 bit) integers in memory. This means that an image with format P\+F\+\_\+\+A8\+R8\+G8\+B8 can be seen as an array of 32 bit integers, defined as 0x\+A\+A\+R\+R\+G\+G\+BB in hexadecimal. The meaning of the letters is described below.


\item[Byte formats (P\+F\+\_\+\+B\+Y\+T\+E\+\_\+$\ast$) ]

These formats have one byte per channel, and their channels in memory are organized in the order they are specified in the format name. For example, P\+F\+\_\+\+B\+Y\+T\+E\+\_\+\+R\+G\+BA consists of blocks of four bytes, one for red, one for green, one for blue, one for alpha.


\item[Short formats (P\+F\+\_\+\+S\+H\+O\+R\+T\+\_\+$\ast$) ]

These formats have one unsigned short (16 bit integer) per channel, and their channels in memory are organized in the order they are specified in the format name. For example, P\+F\+\_\+\+S\+H\+O\+R\+T\+\_\+\+R\+G\+BA consists of blocks of four 16 bit integers, one for red, one for green, one for blue, one for alpha.


\item[Float16 formats (P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+$\ast$) ]

These formats have one 16 bit floating point number per channel, and their channels in memory are organized in the order they are specified in the format name. For example, P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+\+R\+G\+BA consists of blocks of four 16 bit floats, one for red, one for green, one for blue, one for alpha. The 16 bit floats, also called half float) are very similar to the I\+E\+EE single-\/precision floating-\/point standard of the 32 bits floats, except that they have only 5 exponent bits and 10 mantissa. Note that there is no standard C++ data type or C\+PU support to work with these efficiently, but G\+P\+Us can calculate with these much more efficiently than with 32 bit floats.


\item[Float32 formats (P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+$\ast$) ]

These formats have one 32 bit floating point number per channel, and their channels in memory are organized in the order they are specified in the format name. For example, P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+\+R\+G\+BA consists of blocks of four 32 bit floats, one for red, one for green, one for blue, one for alpha. The C++ data type for these 32 bits floats is just \char`\"{}float\char`\"{}.


\item[Compressed formats (P\+F\+\_\+\+D\+XT\mbox{[}1-\/5\mbox{]}) ]

S3\+TC compressed texture formats, \href{http://en.wikipedia.org/wiki/S3TC}{\tt a good description can be found at Wikipedia}


\end{DoxyDescription}\hypertarget{_hardware-_buffers_Colour-channels}{}\subsubsection{Colour channels}\label{_hardware-_buffers_Colour-channels}
The meaning of the channels R,G,B,A,L and X is defined as


\begin{DoxyDescription}
\item[R ]

Red colour component, usually ranging from 0.\+0 (no red) to 1.\+0 (full red).


\item[G ]

Green colour component, usually ranging from 0.\+0 (no green) to 1.\+0 (full green).


\item[B ]

Blue colour component, usually ranging from 0.\+0 (no blue) to 1.\+0 (full blue).


\item[A ]

Alpha component, usually ranging from 0.\+0 (entire transparent) to 1.\+0 (opaque).


\item[L ]

Luminance component, usually ranging from 0.\+0 (black) to 1.\+0 (white). The luminance component is duplicated in the R, G, and B channels to achieve a greyscale image.


\item[X ]

This component is completely ignored.


\end{DoxyDescription}

If none of red, green and blue components, or luminance is defined in a format, these default to 0. For the alpha channel this is different; if no alpha is defined, it defaults to 1.\hypertarget{_hardware-_buffers_Complete-list-of-pixel-formats}{}\subsubsection{List of pixel formats}\label{_hardware-_buffers_Complete-list-of-pixel-formats}
This pixel formats supported by the current version of \hyperlink{namespace_ogre}{Ogre} are


\begin{DoxyDescription}
\item[Byte formats ]

P\+F\+\_\+\+B\+Y\+T\+E\+\_\+\+R\+GB, P\+F\+\_\+\+B\+Y\+T\+E\+\_\+\+B\+GR, P\+F\+\_\+\+B\+Y\+T\+E\+\_\+\+B\+G\+RA, P\+F\+\_\+\+B\+Y\+T\+E\+\_\+\+R\+G\+BA, P\+F\+\_\+\+B\+Y\+T\+E\+\_\+L, P\+F\+\_\+\+B\+Y\+T\+E\+\_\+\+LA, P\+F\+\_\+\+B\+Y\+T\+E\+\_\+A


\item[Short formats ]

P\+F\+\_\+\+S\+H\+O\+R\+T\+\_\+\+R\+G\+BA


\item[Float16 formats ]

P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+R, P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+\+R\+GB, P\+F\+\_\+\+F\+L\+O\+A\+T16\+\_\+\+R\+G\+BA


\item[Float32 formats ]

P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+R, P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+\+R\+GB, P\+F\+\_\+\+F\+L\+O\+A\+T32\+\_\+\+R\+G\+BA


\item[8 bit native endian formats ]

P\+F\+\_\+\+L8, P\+F\+\_\+\+A8, P\+F\+\_\+\+A4\+L4, P\+F\+\_\+\+R3\+G3\+B2


\item[16 bit native endian formats ]

P\+F\+\_\+\+L16, P\+F\+\_\+\+R5\+G6\+B5, P\+F\+\_\+\+B5\+G6\+R5, P\+F\+\_\+\+A4\+R4\+G4\+B4, P\+F\+\_\+\+A1\+R5\+G5\+B5


\item[24 bit native endian formats ]

P\+F\+\_\+\+R8\+G8\+B8, P\+F\+\_\+\+B8\+G8\+R8


\item[32 bit native endian formats ]

P\+F\+\_\+\+A8\+R8\+G8\+B8, P\+F\+\_\+\+A8\+B8\+G8\+R8, P\+F\+\_\+\+B8\+G8\+R8\+A8, P\+F\+\_\+\+R8\+G8\+B8\+A8, P\+F\+\_\+\+X8\+R8\+G8\+B8, P\+F\+\_\+\+X8\+B8\+G8\+R8, P\+F\+\_\+\+A2\+R10\+G10\+B10 P\+F\+\_\+\+A2\+B10\+G10\+R10


\item[Compressed formats ]

P\+F\+\_\+\+D\+X\+T1, P\+F\+\_\+\+D\+X\+T2, P\+F\+\_\+\+D\+X\+T3, P\+F\+\_\+\+D\+X\+T4, P\+F\+\_\+\+D\+X\+T5


\end{DoxyDescription}

For a complete list see \hyperlink{group___image_ga7e0353e7d36d4c2e8468641b7303d39c}{Ogre\+::\+Pixel\+Format}.\hypertarget{_hardware-_buffers_Pixel-boxes}{}\subsubsection{Pixel boxes}\label{_hardware-_buffers_Pixel-boxes}
All methods in \hyperlink{namespace_ogre}{Ogre} that take or return raw image data return a \hyperlink{class_ogre_1_1_pixel_box}{Ogre\+::\+Pixel\+Box} object.

A Pixel\+Box is a primitive describing a volume (3D), image (2D) or line (1D) of pixels in C\+PU memory. It describes the location and data format of a region of memory used for image data, but does not do any memory management in itself.

Inside the memory pointed to by the {\itshape data} member of a pixel box, pixels are stored as a succession of \char`\"{}depth\char`\"{} slices (in Z), each containing \char`\"{}height\char`\"{} rows (Y) of \char`\"{}width\char`\"{} pixels (X).

Dimensions that are not used must be 1. For example, a one dimensional image will have extents (width,1,1). A two dimensional image has extents (width,height,1).

For more information about the members consult the A\+PI documentation \hyperlink{class_ogre_1_1_pixel_box}{Ogre\+::\+Pixel\+Box}. \hypertarget{Shadows}{}\section{Shadows}\label{Shadows}
Shadows are clearly an important part of rendering a believable scene -\/ they provide a more tangible feel to the objects in the scene, and aid the viewer in understanding the spatial relationship between objects. Unfortunately, shadows are also one of the most challenging aspects of 3D rendering, and they are still very much an active area of research. Whilst there are many techniques to render shadows, none is perfect and they all come with advantages and disadvantages. For this reason, \hyperlink{namespace_ogre}{Ogre} provides multiple shadow implementations, with plenty of configuration settings, so you can choose which technique is most appropriate for your scene.

Shadow implementations fall into basically 2 broad categories\+: \href{#Stencil-Shadows}{\tt Stencil Shadows} and \href{#Texture_002dbased-Shadows}{\tt Texture-\/based Shadows}. This describes the method by which the shape of the shadow is generated. In addition, there is more than one way to render the shadow into the scene\+: \href{#Modulative-Shadows}{\tt Modulative Shadows}, which darkens the scene in areas of shadow, and \href{#Additive-Light-Masking}{\tt Additive Light Masking} which by contrast builds up light contribution in areas which are not in shadow. You also have the option of \href{#Integrated-Texture-Shadows}{\tt Integrated Texture Shadows} which gives you complete control over texture shadow application, allowing for complex single-\/pass shadowing shaders. \hyperlink{namespace_ogre}{Ogre} supports all these combinations.\hypertarget{_shadows_Enabling-shadows}{}\subsection{Enabling shadows}\label{_shadows_Enabling-shadows}
Shadows are disabled by default, here’s how you turn them on and configure them in the general sense\+:


\begin{DoxyEnumerate}
\item Enable a shadow technique on the Scene\+Manager as the {\bfseries first} thing you doing your scene setup. It is important that this is done first because the shadow technique can alter the way meshes are loaded. Here’s an example\+:

{\ttfamily m\+Scene\+Mgr-\/$>$set\+Shadow\+Technique(\+S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+S\+T\+E\+N\+C\+I\+L\+\_\+\+A\+D\+D\+I\+T\+I\+V\+E);}
\item Create one or more lights. Note that not all light types are necessarily supported by all shadow techniques, you should check the sections about each technique to check. Note that if certain lights should not cast shadows, you can turn that off by calling set\+Cast\+Shadows(false) on the light, the default is true.
\item Disable shadow casting on objects which should not cast shadows. Call set\+Cast\+Shadows(false) on objects you don’t want to cast shadows, the default for all objects is to cast shadows.
\item Configure shadow far distance. You can limit the distance at which shadows are considered for performance reasons, by calling Scene\+Manager\+::set\+Shadow\+Far\+Distance.
\item Turn off the receipt of shadows on materials that should not receive them. You can turn off the receipt of shadows (note, not the casting of shadows -\/ that is done per-\/object) by calling Material\+::set\+Receive\+Shadows or using the receive\+\_\+shadows material attribute. This is useful for materials which should be considered self-\/illuminated for example. Note that transparent materials are typically excluded from receiving and casting shadows, although see the \href{#transparency_005fcasts_005fshadows}{\tt transparency\+\_\+casts\+\_\+shadows} option for exceptions.
\end{DoxyEnumerate}\hypertarget{_shadows_Opting-out-of-shadows}{}\subsection{Opting out of shadows}\label{_shadows_Opting-out-of-shadows}
By default \hyperlink{namespace_ogre}{Ogre} treats all non-\/transparent objects as shadow casters and receivers (depending on the shadow technique they may not be able to be both at once, check the docs for your chosen technique first). You can disable shadows in various ways\+:


\begin{DoxyDescription}
\item[Turning off shadow casting on the light ]

Calling {\ttfamily Light\+::set\+Cast\+Shadows(false)} will mean this light casts no shadows at all.


\item[Turn off shadow receipt on a material ]

Calling {\ttfamily Material\+::set\+Receive\+Shadows(false)} will prevent any objects using this material from receiving shadows.


\item[Turn off shadow casting on individual objects ]

Calling {\ttfamily Movable\+Object\+::set\+Cast\+Shadows(false)} will disable shadow casting for this object.


\item[Turn off shadows on an entire rendering queue group ]

Calling {\ttfamily Render\+Queue\+Group\+::set\+Shadows\+Enabled(false)} will turn off both shadow casting and receiving on an entire rendering queue group. This is useful because \hyperlink{namespace_ogre}{Ogre} has to do light setup tasks per group in order to preserve the inter-\/group ordering. \hyperlink{namespace_ogre}{Ogre} automatically disables shadows on a number of groups automatically, such as {\ttfamily R\+E\+N\+D\+E\+R\+\_\+\+Q\+U\+E\+U\+E\+\_\+\+B\+A\+C\+K\+G\+R\+O\+U\+ND, R\+E\+N\+D\+E\+R\+\_\+\+Q\+U\+E\+U\+E\+\_\+\+O\+V\+E\+R\+L\+AY, R\+E\+N\+D\+E\+R\+\_\+\+Q\+U\+E\+U\+E\+\_\+\+S\+K\+I\+E\+S\+\_\+\+E\+A\+R\+LY} and {\ttfamily R\+E\+N\+D\+E\+R\+\_\+\+Q\+U\+E\+U\+E\+\_\+\+S\+K\+I\+E\+S\+\_\+\+L\+A\+TE}. If you choose to use more rendering queues (and by default, you won’t be using any more than this plus the ’standard’ queue, so ignore this if you don’t know what it means!), be aware that each one can incur a light setup cost, and you should disable shadows on the additional ones you use if you can.


\end{DoxyDescription}\hypertarget{_shadows_Stencil-Shadows}{}\subsection{Stencil Shadows}\label{_shadows_Stencil-Shadows}
Stencil shadows are a method by which a ’mask’ is created for the screen using a feature called the stencil buffer. This mask can be used to exclude areas of the screen from subsequent renders, and thus it can be used to either include or exclude areas in shadow. They are enabled by calling \hyperlink{class_ogre_1_1_scene_manager_ad716d3752418408f073d9be9bbfe62d0}{Ogre\+::\+Scene\+Manager\+::set\+Shadow\+Technique} with a parameter of either {\ttfamily S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+S\+T\+E\+N\+C\+I\+L\+\_\+\+A\+D\+D\+I\+T\+I\+VE} or {\ttfamily S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+S\+T\+E\+N\+C\+I\+L\+\_\+\+M\+O\+D\+U\+L\+A\+T\+I\+VE}. Because the stencil can only mask areas to be either ’enabled’ or ’disabled’, stencil shadows have ’hard’ edges, that is to say clear dividing lines between light and shadow -\/ it is not possible to soften these edges.

In order to generate the stencil, ’shadow volumes’ are rendered by extruding the silhouette of the shadow caster away from the light. Where these shadow volumes intersect other objects (or the caster, since self-\/shadowing is supported using this technique), the stencil is updated, allowing subsequent operations to differentiate between light and shadow. How exactly this is used to render the shadows depends on whether \href{#Modulative-Shadows}{\tt Modulative Shadows} or \href{#Additive-Light-Masking}{\tt Additive Light Masking} is being used. Objects can both cast and receive stencil shadows, so self-\/shadowing is inbuilt.

The advantage of stencil shadows is that they can do self-\/shadowing simply on low-\/end hardware, provided you keep your poly count under control. In contrast doing self-\/shadowing with texture shadows requires a fairly modern machine (See \href{#Texture_002dbased-Shadows}{\tt Texture-\/based Shadows}). For this reason, you’re likely to pick stencil shadows if you need an accurate shadowing solution for an application aimed at older or lower-\/spec machines.

The disadvantages of stencil shadows are numerous though, especially on more modern hardware. Because stencil shadows are a geometric technique, they are inherently more costly the higher the number of polygons you use, meaning you are penalized the more detailed you make your meshes. The fillrate cost, which comes from having to render shadow volumes, also escalates the same way. Since more modern applications are likely to use higher polygon counts, stencil shadows can start to become a bottleneck. In addition, the visual aspects of stencil shadows are pretty primitive -\/ your shadows will always be hard-\/edged, and you have no possibility of doing clever things with shaders since the stencil is not available for manipulation there. Therefore, if your application is aimed at higher-\/end machines you should definitely consider switching to texture shadows (See \href{#Texture_002dbased-Shadows}{\tt Texture-\/based Shadows}).

There are a number of issues to consider which are specific to stencil shadows\+:


\begin{DoxyItemize}
\item \href{#CPU-Overhead}{\tt C\+PU Overhead}
\item \href{#Extrusion-distance}{\tt Extrusion distance}
\item \href{#Camera-far-plane-positioning}{\tt Camera far plane positioning}
\item \href{#Mesh-edge-lists}{\tt Mesh edge lists}
\item \href{#The-Silhouette-Edge}{\tt The Silhouette Edge}
\item \href{#Be-realistic}{\tt Be realistic}
\item \href{#Stencil-Optimisations-Performed-By-Ogre}{\tt Stencil Optimisations Performed By Ogre}
\end{DoxyItemize}

\label{_CPU-Overhead}%
\label{_CPU-Overhead-1}%


\subsection*{C\+PU Overhead}

Calculating the shadow volume for a mesh can be expensive, and it has to be done on the C\+PU, it is not a hardware accelerated feature. Therefore, you can find that if you overuse this feature, you can create a C\+PU bottleneck for your application. \hyperlink{namespace_ogre}{Ogre} quite aggressively eliminates objects which cannot be casting shadows on the frustum, but there are limits to how much it can do, and large, elongated shadows (e.\+g. representing a very low sun position) are very difficult to cull efficiently. Try to avoid having too many shadow casters around at once, and avoid long shadows if you can. Also, make use of the ’shadow far distance’ parameter on the Scene\+Manager, this can eliminate distant shadow casters from the shadow volume construction and save you some time, at the expense of only having shadows for closer objects. Lastly, make use of Ogre’s Level-\/\+Of-\/\+Detail (L\+OD) features; you can generate automatically calculated L\+O\+Ds for your meshes in code (see the Mesh A\+PI docs) or when using the mesh tools such as Ogre\+X\+M\+L\+Converter and Ogre\+Mesh\+Upgrader. Alternatively, you can assign your own manual L\+O\+Ds by providing alternative mesh files at lower detail levels. Both methods will cause the shadow volume complexity to decrease as the object gets further away, which saves you valuable volume calculation time.

\label{_Extrusion-distance}%
\label{_Extrusion-distance-1}%


\subsection*{Extrusion distance}

When vertex programs are not available, \hyperlink{namespace_ogre}{Ogre} can only extrude shadow volumes a finite distance from the object. If an object gets too close to a light, any finite extrusion distance will be inadequate to guarantee all objects will be shadowed properly by this object. Therefore, you are advised not to let shadow casters pass too close to light sources if you can avoid it, unless you can guarantee that your target audience will have vertex program capable hardware (in this case, \hyperlink{namespace_ogre}{Ogre} extrudes the volume to infinity using a vertex program so the problem does not occur). When infinite extrusion is not possible, \hyperlink{namespace_ogre}{Ogre} uses finite extrusion, either derived from the attenuation range of a light (in the case of a point light or spotlight), or a fixed extrusion distance set in the application in the case of directional lights. To change the directional light extrusion distance, use Scene\+Manager\+::set\+Shadow\+Directional\+Light\+Extrusion\+Distance.

\label{_Camera-far-plane-positioning}%
\label{_Camera-far-plane-positioning-1}%


\subsection*{Camera far plane positioning}

Stencil shadow volumes rely very much on not being clipped by the far plane. When you enable stencil shadows, \hyperlink{namespace_ogre}{Ogre} internally changes the far plane settings of your cameras such that there is no far plane -\/ i.\+e. it is placed at infinity (Camera\+::set\+Far\+Clip\+Distance(0)). This avoids artifacts caused by clipping the dark caps on shadow volumes, at the expense of a (very) small amount of depth precision.

\label{_Mesh-edge-lists}%
\label{_Mesh-edge-lists-1}%


\subsection*{Mesh edge lists}

Stencil shadows can only be calculated when an ’edge list’ has been built for all the geometry in a mesh. The official exporters and tools automatically build this for you (or have an option to do so), but if you create your own meshes, you must remember to build edge lists for them before using them with stencil shadows -\/ you can do that by using Ogre\+Mesh\+Upgrade or Ogre\+Xml\+Converter, or by calling Mesh\+::build\+Edge\+List before you export or use the mesh. If a mesh doesn’t have edge lists, O\+G\+RE assumes that it is not supposed to cast stencil shadows.

\label{_The-Silhouette-Edge}%
\label{_The-Silhouette-Edge-1}%


\subsection*{The Silhouette Edge}

Stencil shadowing is about finding a silhouette of the mesh, and projecting it away to form a volume. What this means is that there is a definite boundary on the shadow caster between light and shadow; a set of edges where where the triangle on one side is facing toward the light, and one is facing away. This produces a sharp edge around the mesh as the transition occurs. Provided there is little or no other light in the scene, and the mesh has smooth normals to produce a gradual light change in its underlying shading, the silhouette edge can be hidden -\/ this works better the higher the tessellation of the mesh. However, if the scene includes ambient light, then the difference is far more marked. This is especially true when using \href{#Modulative-Shadows}{\tt Modulative Shadows}, because the light contribution of each shadowed area is not taken into account by this simplified approach, and so using 2 or more lights in a scene using modulative stencil shadows is not advisable; the silhouette edges will be very marked. Additive lights do not suffer from this as badly because each light is masked individually, meaning that it is only ambient light which can show up the silhouette edges.

\label{_Be-realistic}%
\label{_Be-realistic-1}%


\subsection*{Be realistic}

Don’t expect to be able to throw any scene using any hardware at the stencil shadow algorithm and expect to get perfect, optimum speed results. Shadows are a complex and expensive technique, so you should impose some reasonable limitations on your placing of lights and objects; they’re not really that restricting, but you should be aware that this is not a complete free-\/for-\/all.


\begin{DoxyItemize}
\item Try to avoid letting objects pass very close (or even through) lights -\/ it might look nice but it’s one of the cases where artifacts can occur on machines not capable of running vertex programs.
\item Be aware that shadow volumes do not respect the ’solidity’ of the objects they pass through, and if those objects do not themselves cast shadows (which would hide the effect) then the result will be that you can see shadows on the other side of what should be an occluding object.
\item Make use of Scene\+Manager\+::set\+Shadow\+Far\+Distance to limit the number of shadow volumes constructed
\item Make use of L\+OD to reduce shadow volume complexity at distance
\item Avoid very long (dusk and dawn) shadows -\/ they exacerbate other issues such as volume clipping, fillrate, and cause many more objects at a greater distance to require volume construction.

\label{_Stencil-Optimisations-Performed-By-Ogre}%
\label{_Stencil-Optimisations-Performed-By-Ogre-1}%

\end{DoxyItemize}

\subsection*{Stencil Optimisations Performed By \hyperlink{namespace_ogre}{Ogre}}

Despite all that, stencil shadows can look very nice (especially with \href{#Additive-Light-Masking}{\tt Additive Light Masking}) and can be fast if you respect the rules above. In addition, \hyperlink{namespace_ogre}{Ogre} comes pre-\/packed with a lot of optimisations which help to make this as quick as possible. This section is more for developers or people interested in knowing something about the ’under the hood’ behaviour of \hyperlink{namespace_ogre}{Ogre}.


\begin{DoxyDescription}
\item[Vertex program extrusion ]

As previously mentioned, \hyperlink{namespace_ogre}{Ogre} performs the extrusion of shadow volumes in hardware on vertex program-\/capable hardware (e.\+g. Ge\+Force3, Radeon 8500 or better). This has 2 major benefits; the obvious one being speed, but secondly that vertex programs can extrude points to infinity, which the fixed-\/function pipeline cannot, at least not without performing all calculations in software. This leads to more robust volumes, and also eliminates more than half the volume triangles on directional lights since all points are projected to a single point at infinity.


\item[Scissor test optimisation ]

\hyperlink{namespace_ogre}{Ogre} uses a scissor rectangle to limit the effect of point / spot lights when their range does not cover the entire viewport; that means we save fillrate when rendering stencil volumes, especially with distant lights


\item[Z-\/\+Pass and Z-\/\+Fail algorithms ]

The Z-\/\+Fail algorithm, often attributed to John Carmack, is used in \hyperlink{namespace_ogre}{Ogre} to make sure shadows are robust when the camera passes through the shadow volume. However, the Z-\/\+Fail algorithm is more expensive than the traditional Z-\/\+Pass; so \hyperlink{namespace_ogre}{Ogre} detects when Z-\/\+Fail is required and only uses it then, Z-\/\+Pass is used at all other times.


\item[2-\/\+Sided stenciling and stencil wrapping ]

\hyperlink{namespace_ogre}{Ogre} supports the 2-\/\+Sided stenciling / stencil wrapping extensions, which when supported allow volumes to be rendered in a single pass instead of having to do one pass for back facing tris and another for front-\/facing tris. This doesn’t save fillrate, since the same number of stencil updates are done, but it does save primitive setup and the overhead incurred in the driver every time a render call is made.


\item[Aggressive shadow volume culling ]

\hyperlink{namespace_ogre}{Ogre} is pretty good at detecting which lights could be affecting the frustum, and from that, which objects could be casting a shadow on the frustum. This means we don’t waste time constructing shadow geometry we don’t need. Setting the shadow far distance is another important way you can reduce stencil shadow overhead since it culls far away shadow volumes even if they are visible, which is beneficial in practice since you’re most interested in shadows for close-\/up objects.


\end{DoxyDescription}\hypertarget{_shadows_Texture_002dbased-Shadows}{}\subsection{Texture-\/based Shadows}\label{_shadows_Texture_002dbased-Shadows}
Texture shadows involve rendering shadow casters from the point of view of the light into a texture, which is then projected onto shadow receivers. The main advantage of texture shadows as opposed to \href{#Stencil-Shadows}{\tt Stencil Shadows} is that the overhead of increasing the geometric detail is far lower, since there is no need to perform per-\/triangle calculations. Most of the work in rendering texture shadows is done by the graphics card, meaning the technique scales well when taking advantage of the latest cards, which are at present outpacing C\+P\+Us in terms of their speed of development. In addition, texture shadows are {\bfseries much} more customisable -\/ you can pull them into shaders to apply as you like (particularly with \href{#Integrated-Texture-Shadows}{\tt Integrated Texture Shadows}, you can perform filtering to create softer shadows or perform other special effects on them. Basically, most modern engines use texture shadows as their primary shadow technique simply because they are more powerful, and the increasing speed of G\+P\+Us is rapidly amortizing the fillrate / texture access costs of using them.

The main disadvantage to texture shadows is that, because they are simply a texture, they have a fixed resolution which means if stretched, the pixellation of the texture can become obvious. There are ways to combat this though\+:


\begin{DoxyDescription}
\item[Choosing a projection basis ]

The simplest projection is just to render the shadow casters from the lights perspective using a regular camera setup. This can look bad though, so there are many other projections which can help to improve the quality from the main camera’s perspective. O\+G\+RE supports pluggable projection bases via it’s Shadow\+Camera\+Setup class, and comes with several existing options -\/ {\bfseries Uniform} (which is the simplest), {\bfseries Uniform Focussed} (which is still a normal camera projection, except that the camera is focussed into the area that the main viewing camera is looking at), Li\+S\+P\+SM (Light Space Perspective Shadow Mapping -\/ which both focusses and distorts the shadow frustum based on the main view camera) and Plan Optimal (which seeks to optimise the shadow fidelity for a single receiver plane).


\item[Filtering ]

You can also sample the shadow texture multiple times rather than once to soften the shadow edges and improve the appearance. Percentage Closest Filtering (P\+CF) is the most popular approach, although there are multiple variants depending on the number and pattern of the samples you take. Our shadows demo includes a 5-\/tap P\+CF example combined with depth shadow mapping.


\item[Using a larger texture ]

Again as G\+P\+Us get faster and gain more memory, you can scale up to take advantage of this.


\end{DoxyDescription}

If you combine all 3 of these techniques you can get a very high quality shadow solution.

The other issue is with point lights. Because texture shadows require a render to texture in the direction of the light, omnidirectional lights (point lights) would require 6 renders to totally cover all the directions shadows might be cast. For this reason, \hyperlink{namespace_ogre}{Ogre} primarily supports directional lights and spotlights for generating texture shadows; you can use point lights but they will only work if off-\/camera since they are essentially turned into a spotlight shining into your camera frustum for the purposes of texture shadows.

\label{_Directional-Lights}%


\subsection*{Directional Lights}

Directional lights in theory shadow the entire scene from an infinitely distant light. Now, since we only have a finite texture which will look very poor quality if stretched over the entire scene, clearly a simplification is required. \hyperlink{namespace_ogre}{Ogre} places a shadow texture over the area immediately in front of the camera, and moves it as the camera moves (although it rounds this movement to multiples of texels so that the slight ’swimming shadow’ effect caused by moving the texture is minimised). The range to which this shadow extends, and the offset used to move it in front of the camera, are configurable (See \href{#Configuring-Texture-Shadows}{\tt Configuring Texture Shadows}). At the far edge of the shadow, \hyperlink{namespace_ogre}{Ogre} fades out the shadow based on other configurable parameters so that the termination of the shadow is softened.

\label{_Spotlights}%


\subsection*{Spotlights}

Spotlights are much easier to represent as renderable shadow textures than directional lights, since they are naturally a frustum. \hyperlink{namespace_ogre}{Ogre} represents spotlight directly by rendering the shadow from the light position, in the direction of the light cone; the field-\/of-\/view of the texture camera is adjusted based on the spotlight falloff angles. In addition, to hide the fact that the shadow texture is square and has definite edges which could show up outside the spotlight, \hyperlink{namespace_ogre}{Ogre} uses a second texture unit when projecting the shadow onto the scene which fades out the shadow gradually in a projected circle around the spotlight.

\label{_Point-Lights}%


\subsection*{Point Lights}

As mentioned above, to support point lights properly would require multiple renders (either 6 for a cubic render or perhaps 2 for a less precise parabolic mapping), so rather than do that we approximate point lights as spotlights, where the configuration is changed on the fly to make the light shine from its position over the whole of the viewing frustum. This is not an ideal setup since it means it can only really work if the point light’s position is out of view, and in addition the changing parameterisation can cause some ’swimming’ of the texture. Generally we recommend avoiding making point lights cast texture shadows.

\label{_Shadow-Casters-and-Shadow-Receivers}%


\subsection*{Shadow Casters and Shadow Receivers}

To enable texture shadows, use the shadow technique S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+M\+O\+D\+U\+L\+A\+T\+I\+VE or S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+A\+D\+D\+I\+T\+I\+VE; as the name suggests this produces \href{#Modulative-Shadows}{\tt Modulative Shadows} or \href{#Additive-Light-Masking}{\tt Additive Light Masking} respectively. The cheapest and simplest texture shadow techniques do not use depth information, they merely render casters to a texture and render this onto receivers as plain colour -\/ this means self-\/shadowing is not possible using these methods. This is the default behaviour if you use the automatic, fixed-\/function compatible (and thus usable on lower end hardware) texture shadow techniques. You can however use shaders-\/based techniques through custom shadow materials for casters and receivers to perform more complex shadow algorithms, such as depth shadow mapping which does allow self-\/shadowing. O\+G\+RE comes with an example of this in its shadows demo, although it’s only usable on Shader Model 2 cards or better. Whilst fixed-\/function depth shadow mapping is available in Open\+GL, it was never standardised in Direct3D so using shaders in custom caster \& receiver materials is the only portable way to do it. If you use this approach, call Scene\+Manager\+::set\+Shadow\+Texture\+Self\+Shadow with a parameter of ’true’ to allow texture shadow casters to also be receivers. If you’re not using depth shadow mapping, O\+G\+RE divides shadow casters and receivers into 2 disjoint groups. Simply by turning off shadow casting on an object, you automatically make it a shadow receiver (although this can be disabled by setting the ’receive\+\_\+shadows’ option to ’false’ in a material script. Similarly, if an object is set as a shadow caster, it cannot receive shadows.\hypertarget{_shadows_Configuring-Texture-Shadows}{}\subsection{Configuring Texture Shadows}\label{_shadows_Configuring-Texture-Shadows}
There are a number of settings which will help you configure your texture-\/based shadows so that they match your requirements.


\begin{DoxyItemize}
\item \href{#Maximum-number-of-shadow-textures}{\tt Maximum number of shadow textures}
\item \href{#Shadow-texture-size}{\tt Shadow texture size}
\item \href{#Shadow-far-distance}{\tt Shadow far distance}
\item \href{#Shadow-texture-offset-Directional-Lights_0029}{\tt Shadow texture offset (Directional Lights)}
\item \href{#Shadow-fade-settings}{\tt Shadow fade settings}
\item \href{#Custom-shadow-camera-setups}{\tt Custom shadow camera setups}
\item \href{#Shadow-texture-Depth-Buffer-sharing}{\tt Shadow texture Depth Buffer sharing}
\item \href{#Integrated-Texture-Shadows}{\tt Integrated Texture Shadows}
\end{DoxyItemize}

\label{_Maximum-number-of-shadow-textures}%
\label{_Maximum-number-of-shadow-textures-1}%


\subsection*{Maximum number of shadow textures}

Shadow textures take up texture memory, and to avoid stalling the rendering pipeline \hyperlink{namespace_ogre}{Ogre} does not reuse the same shadow texture for multiple lights within the same frame. This means that each light which is to cast shadows must have its own shadow texture. In practice, if you have a lot of lights in your scene you would not wish to incur that sort of texture overhead. You can adjust this manually by simply turning off shadow casting for lights you do not wish to cast shadows. In addition, you can set a maximum limit on the number of shadow textures \hyperlink{namespace_ogre}{Ogre} is allowed to use by calling Scene\+Manager\+::set\+Shadow\+Texture\+Count. Each frame, \hyperlink{namespace_ogre}{Ogre} determines the lights which could be affecting the frustum, and then allocates the number of shadow textures it is allowed to use to the lights on a first-\/come-\/first-\/served basis. Any additional lights will not cast shadows that frame. Note that you can set the number of shadow textures and their size at the same time by using the Scene\+Manager\+::set\+Shadow\+Texture\+Settings method; this is useful because both the individual calls require the potential creation / destruction of texture resources.

\label{_Shadow-texture-size}%
\label{_Shadow-texture-size-1}%


\subsection*{Shadow texture size}

The size of the textures used for rendering the shadow casters into can be altered; clearly using larger textures will give you better quality shadows, but at the expense of greater memory usage. Changing the texture size is done by calling Scene\+Manager\+::set\+Shadow\+Texture\+Size -\/ textures are assumed to be square and you must specify a texture size that is a power of 2. Be aware that each modulative shadow texture will take size$\ast$size$\ast$3 bytes of texture memory. {\bfseries Important}\+: if you use the GL render system your shadow texture size can only be larger (in either dimension) than the size of your primary window surface if the hardware supports the Frame Buffer Object (F\+BO) or Pixel Buffer Object (P\+BO) extensions. Most modern cards support this now, but be careful of older cards -\/ you can check the ability of the hardware to manage this through ogre\+Root-\/$>$get\+Render\+System()-\/$>$get\+Capabilities()-\/$>$has\+Capability(\+R\+S\+C\+\_\+\+H\+W\+R\+E\+N\+D\+E\+R\+\_\+\+T\+O\+\_\+\+T\+E\+X\+T\+U\+R\+E). If this returns false, if you create a shadow texture larger in any dimension than the primary surface, the rest of the shadow texture will be blank.

\label{_Shadow-far-distance}%
\label{_Shadow-far-distance-1}%


\subsection*{Shadow far distance}

This determines the distance at which shadows are terminated; it also determines how far into the distance the texture shadows for directional lights are stretched -\/ by reducing this value, or increasing the texture size, you can improve the quality of shadows from directional lights at the expense of closer shadow termination or increased memory usage, respectively.

\label{_Shadow-texture-offset-Directional-Lights_0029}%


\subsection*{Shadow texture offset (Directional Lights)}

As mentioned above in the directional lights section, the rendering of shadows for directional lights is an approximation that allows us to use a single render to cover a largish area with shadows. This offset parameter affects how far from the camera position the center of the shadow texture is offset, as a proportion of the shadow far distance. The greater this value, the more of the shadow texture is ’useful’ to you since it’s ahead of the camera, but also the further you offset it, the more chance there is of accidentally seeing the edge of the shadow texture at more extreme angles. You change this value by calling Scene\+Manager\+::set\+Shadow\+Dir\+Light\+Texture\+Offset, the default is 0.\+6.

\label{_Shadow-fade-settings}%
\label{_Shadow-fade-settings-1}%


\subsection*{Shadow fade settings}

Shadows fade out before the shadow far distance so that the termination of shadow is not abrupt. You can configure the start and end points of this fade by calling the Scene\+Manager\+::set\+Shadow\+Texture\+Fade\+Start and Scene\+Manager\+::set\+Shadow\+Texture\+Fade\+End methods, both take distances as a proportion of the shadow far distance. Because of the inaccuracies caused by using a square texture and a radial fade distance, you cannot use 1.\+0 as the fade end, if you do you’ll see artifacts at the extreme edges. The default values are 0.\+7 and 0.\+9, which serve most purposes but you can change them if you like.

\section*{Texture shadows and vertex / fragment programs}

When rendering shadow casters into a modulative shadow texture, \hyperlink{namespace_ogre}{Ogre} turns off all textures, and all lighting contributions except for ambient light, which it sets to the colour of the shadow (\href{#Shadow-Colour}{\tt Shadow Colour}). For additive shadows, it render the casters into a black \& white texture instead. This is enough to render shadow casters for fixed-\/function material techniques, however where a vertex program is used \hyperlink{namespace_ogre}{Ogre} doesn’t have so much control. If you use a vertex program in the {\bfseries first pass} of your technique, then you must also tell ogre which vertex program you want it to use when rendering the shadow caster; see \href{#Shadows-and-Vertex-Programs}{\tt Shadows and Vertex Programs} for full details.

\label{_Custom-shadow-camera-setups}%
\label{_Custom-shadow-camera-setups-1}%


\subsection*{Custom shadow camera setups}

As previously mentioned, one of the downsides of texture shadows is that the texture resolution is finite, and it’s possible to get aliasing when the size of the shadow texel is larger than a screen pixel, due to the projection of the texture. In order to address this, you can specify alternative projection bases by using or creating subclasses of the Shadow\+Camera\+Setup class. The default version is called Default\+Shadow\+Camera\+Setup and this sets up a simple regular frustum for point and spotlights, and an orthographic frustum for directional lights. There is also a Plane\+Optimal\+Shadow\+Camera\+Setup class which specialises the projection to a plane, thus giving you much better definition provided your shadow receivers exist mostly in a single plane. Other setup classes (e.\+g. you might create a perspective or trapezoid shadow mapping version) can be created and plugged in at runtime, either on individual lights or on the Scene\+Manager as a whole.

\label{_Shadow-texture-Depth-Buffer-sharing}%
\label{_Shadow-texture-Depth-Buffer-sharing-1}%


\subsection*{Shadow texture Depth Buffer sharing}

Shadow textures need a depth buffer like many other R\+Ts (Render Textures). Prior to \hyperlink{namespace_ogre}{Ogre} 1.\+8, the depth buffer behavior was left undefined leaving a very small possibility of causing inconsistencies across different window resolutions and render systems. Depending on the render window’s resolutions and/or rendersystem being used, the depth buffer might been shared with the render window or a new one could get created to suite the shadow textures. If the application was depending on the depth buffer contents from the previous scene render (that is, no clear was performed) where a shadow texture render pass was in the middle; then the depth buffer would’ve contained garbage (but not consistent on all machines) causing graphical glitches hard to spot.

From \hyperlink{namespace_ogre}{Ogre} 1.\+8 onwards the depth buffer usage \& sharing can be flexible controlled through the use of depth pool I\+Ds. These pool I\+Ds are not specifically part of shadow textures, but rather anything involving R\+Ts. All R\+Ts with the same pool ID share the same depth buffers when possible (following Render\+System A\+PI rules, check Render\+System\+Capabilities flags to find out what the behavior will be). The default ID for shadow textures is 1; which is the same default value for render windows, and R\+T\+Ts; thus maintaining the same behavior with older applications while achieving maximum memory saving and performance efficiency because the number of created depth buffers is as lowest as possible.

However there are some reasons to put shadow textures in a separate pool. This holds specially true if the application depends on the previous contents from the depth buffer before the shadow pass, instead of doing a clear\+:


\begin{DoxyItemize}
\item In Direct3\+D9, the shadow texture is more likely to share the depth buffer with the render window at high resolutions (when the window is bigger than the shadow texture resolution), but at low resolutions it won’t be shared, thus causing two different behaviors. Also probably the shadow texture will share the depth buffers with most other R\+T\+Ts (i.\+e. compositors)
\item In Open\+GL 2.\+1, the shadow texture can’t be shared with the main render window; and most likely will N\+OT be shared with many other R\+T\+Ts (i.\+e. compositors) since O\+GL 2.\+1 has a requirement that texture resolutions should exactly match, while D3\+D9 specifies depth buffers can be shared as long as the resolutions are equal or less.
\end{DoxyItemize}

For example, the Deferred\+Shading sample suffers from this problem. If this is a problem for a particular effect you’re trying to achieve, you can specify a custom pool ID so that shadow textures get their own depth buffer(s), ensuring they aren’t shared with other R\+Ts. You can set the pool\+Id parameter from either Scene\+Manager\+::set\+Shadow\+Texture\+Settings or set\+Shadow\+Texture\+Config


\begin{DoxyCode}
mSceneMgr->setShadowTextureSettings( size, count, format, PoolId );
mSceneMgr->setShadowTextureConfig( 0, 512, 512, \hyperlink{group___image_gga7e0353e7d36d4c2e8468641b7303d39cab63dbcddd53d1f766d742fd557c26be4}{PF\_FLOAT16\_R}, 50 );
\end{DoxyCode}


Note a pool\+Id of 0 will make the shadow textures not to use a depth buffer, which isn’t usually a desired behavior.\hypertarget{_shadows_Integrated-Texture-Shadows}{}\subsubsection{Integrated Texture Shadows}\label{_shadows_Integrated-Texture-Shadows}
Texture shadows have one major advantage over stencil shadows -\/ the data used to represent them can be referenced in regular shaders. Whilst the default texture shadow modes (S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+M\+O\+D\+U\+L\+A\+T\+I\+VE and S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+A\+D\+D\+I\+T\+I\+VE) automatically render shadows for you, their disadvantage is that because they are generalised add-\/ons to your own materials, they tend to take more passes of the scene to use. In addition, you don’t have a lot of control over the composition of the shadows.

Here is where ’integrated’ texture shadows step in. Both of the texture shadow types above have alternative versions called S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+M\+O\+D\+U\+L\+A\+T\+I\+V\+E\+\_\+\+I\+N\+T\+E\+G\+R\+A\+T\+ED and S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+A\+D\+D\+I\+T\+I\+V\+E\+\_\+\+I\+N\+T\+E\+G\+R\+A\+T\+ED, where instead of rendering the shadows for you, it just creates the texture shadow and then expects you to use that shadow texture as you see fit when rendering receiver objects in the scene. The downside is that you have to take into account shadow receipt in every one of your materials if you use this option -\/ the upside is that you have total control over how the shadow textures are used. The big advantage here is that you can can perform more complex shading, taking into account shadowing, than is possible using the generalised bolt-\/on approaches, A\+ND you can probably write them in a smaller number of passes, since you know precisely what you need and can combine passes where possible. When you use one of these shadowing approaches, the only difference between additive and modulative is the colour of the casters in the shadow texture (the shadow colour for modulative, black for additive) -\/ the actual calculation of how the texture affects the receivers is of course up to you. No separate modulative pass will be performed, and no splitting of your materials into ambient / per-\/light / decal etc will occur -\/ absolutely everything is determined by your original material (which may have modulative passes or per-\/light iteration if you want of course, but it’s not required).

You reference a shadow texture in a material which implements this approach by using the ’\href{#content_005ftype}{\tt content\+\_\+type} shadow’ directive in your \href{#Texture-Units}{\tt texture\+\_\+unit}. It implicitly references a shadow texture based on the number of times you’ve used this directive in the same pass, and the light\+\_\+start option or light-\/based pass iteration, which might start the light index higher than 0.\hypertarget{_shadows_Modulative-Shadows}{}\subsection{Modulative Shadows}\label{_shadows_Modulative-Shadows}
Modulative shadows work by darkening an already rendered scene with a fixed colour. First, the scene is rendered normally containing all the objects which will be shadowed, then a modulative pass is done per light, which darkens areas in shadow. Finally, objects which do not receive shadows are rendered.

There are 2 modulative shadow techniques; stencil-\/based (See \href{#Stencil-Shadows}{\tt Stencil Shadows} \+: S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+S\+T\+E\+N\+C\+I\+L\+\_\+\+M\+O\+D\+U\+L\+A\+T\+I\+VE) and texture-\/based (See \href{#Texture_002dbased-Shadows}{\tt Texture-\/based Shadows} \+: S\+H\+A\+D\+O\+W\+T\+Y\+P\+E\+\_\+\+T\+E\+X\+T\+U\+R\+E\+\_\+\+M\+O\+D\+U\+L\+A\+T\+I\+VE). Modulative shadows are an inaccurate lighting model, since they darken the areas of shadow uniformly, irrespective of the amount of light which would have fallen on the shadow area anyway. However, they can give fairly attractive results for a much lower overhead than more ’correct’ methods like \href{#Additive-Light-Masking}{\tt Additive Light Masking}, and they also combine well with pre-\/baked static lighting (such as pre-\/calculated lightmaps), which additive lighting does not. The main thing to consider is that using multiple light sources can result in overly dark shadows (where shadows overlap, which intuitively looks right in fact, but it’s not physically correct) and artifacts when using stencil shadows (See \href{#The-Silhouette-Edge}{\tt The Silhouette Edge}).

\label{_Shadow-Colour}%
\label{_Shadow-Colour-1}%


\subsection*{Shadow Colour}

The colour which is used to darken the areas in shadow is set by Scene\+Manager\+::set\+Shadow\+Colour; it defaults to a dark grey (so that the underlying colour still shows through a bit).

Note that if you’re using texture shadows you have the additional option of using \href{#Integrated-Texture-Shadows}{\tt Integrated Texture Shadows} rather than being forced to have a separate pass of the scene to render shadows. In this case the ’modulative’ aspect of the shadow technique just affects the colour of the shadow texture.\hypertarget{_shadows_Additive-Light-Masking}{}\subsection{Additive Light Masking}\label{_shadows_Additive-Light-Masking}
Additive light masking is about rendering the scene many times, each time representing a single light contribution whose influence is masked out in areas of shadow. Each pass is combined with (added to) the previous one such that when all the passes are complete, all the light contribution has correctly accumulated in the scene, and each light has been prevented from affecting areas which it should not be able to because of shadow casters. This is an effective technique which results in very realistic looking lighting, but it comes at a price\+: more rendering passes.

As many technical papers (and game marketing) will tell you, rendering realistic lighting like this requires multiple passes. Being a friendly sort of engine, \hyperlink{namespace_ogre}{Ogre} frees you from most of the hard work though, and will let you use the exact same material definitions whether you use this lighting technique or not (for the most part, see \href{#Pass-Classification-and-Vertex-Programs}{\tt Pass Classification and Vertex Programs}). In order to do this technique, \hyperlink{namespace_ogre}{Ogre} automatically categorises the \href{#Passes}{\tt Passes} you define in your materials into 3 types\+:


\begin{DoxyEnumerate}
\item ambient Passes categorised as ’ambient’ include any base pass which is not lit by any particular light, i.\+e. it occurs even if there is no ambient light in the scene. The ambient pass always happens first, and sets up the initial depth value of the fragments, and the ambient colour if applicable. It also includes any emissive / self illumination contribution. Only textures which affect ambient light (e.\+g. ambient occlusion maps) should be rendered in this pass.
\item diffuse/specular Passes categorised as ’diffuse/specular’ (or ’per-\/light’) are rendered once per light, and each pass contributes the diffuse and specular colour from that single light as reflected by the diffuse / specular terms in the pass. Areas in shadow from that light are masked and are thus not updated. The resulting masked colour is added to the existing colour in the scene. Again, no textures are used in this pass (except for textures used for lighting calculations such as normal maps).
\item decal Passes categorised as ’decal’ add the final texture colour to the scene, which is modulated by the accumulated light built up from all the ambient and diffuse/specular passes.
\end{DoxyEnumerate}

In practice, \href{#Passes}{\tt Passes} rarely fall nicely into just one of these categories. For each Technique, \hyperlink{namespace_ogre}{Ogre} compiles a list of ’\+Illumination Passes’, which are derived from the user defined passes, but can be split, to ensure that the divisions between illumination pass categories can be maintained. For example, if we take a very simple material definition\+:


\begin{DoxyCode}
material TestIllumination
\{
    technique
    \{
        pass
        \{
            ambient 0.5 0.2 0.2 
            diffuse 1 0 0  
            specular 1 0.8 0.8 15
            texture\_unit
            \{
                texture grass.png
            \}
        \}
    \}
\}
\end{DoxyCode}


\hyperlink{namespace_ogre}{Ogre} will split this into 3 illumination passes, which will be the equivalent of this\+:


\begin{DoxyCode}
material TestIlluminationSplitIllumination
\{
    technique
    \{
        \textcolor{comment}{// Ambient pass}
        pass
        \{
            ambient 0.5 0.2 0.2 
            diffuse 0 0 0
            specular 0 0 0
        \}

        \textcolor{comment}{// Diffuse / specular pass}
        pass
        \{
            scene\_blend add
            iteration once\_per\_light
            diffuse 1 0 0  
            specular 1 0.8 0.8 15
        \}

        \textcolor{comment}{// Decal pass}
        pass
        \{
            scene\_blend modulate
            lighting off
            texture\_unit
            \{
                texture grass.png
            \}
        \}
    \}
\}
\end{DoxyCode}


So as you can see, even a simple material requires a minimum of 3 passes when using this shadow technique, and in fact it requires (num\+\_\+lights + 2) passes in the general sense. You can use more passes in your original material and \hyperlink{namespace_ogre}{Ogre} will cope with that too, but be aware that each pass may turn into multiple ones if it uses more than one type of light contribution (ambient vs diffuse/specular) and / or has texture units. The main nice thing is that you get the full multipass lighting behaviour even if you don’t define your materials in terms of it, meaning that your material definitions can remain the same no matter what lighting approach you decide to use.

\label{_Manually-Categorising-Illumination-Passes}%
\label{_Manually-Categorising-Illumination-Passes-1}%


\subsection*{Manually Categorising Illumination Passes}

Alternatively, if you want more direct control over the categorisation of your passes, you can use the \href{#illumination_005fstage}{\tt illumination\+\_\+stage} option in your pass to explicitly assign a pass unchanged to an illumination stage. This way you can make sure you know precisely how your material will be rendered under additive lighting conditions.

\label{_Pass-Classification-and-Vertex-Programs}%
\label{_Pass-Classification-and-Vertex-Programs-1}%


\subsection*{Pass Classification and Vertex Programs}

\hyperlink{namespace_ogre}{Ogre} is pretty good at classifying and splitting your passes to ensure that the multipass rendering approach required by additive lighting works correctly without you having to change your material definitions. However, there is one exception; when you use vertex programs, the normal lighting attributes ambient, diffuse, specular etc are not used, because all of that is determined by the vertex program. \hyperlink{namespace_ogre}{Ogre} has no way of knowing what you’re doing inside that vertex program, so you have to tell it.

In practice this is very easy. Even though your vertex program could be doing a lot of complex, highly customised processing, it can still be classified into one of the 3 types listed above. All you need to do to tell \hyperlink{namespace_ogre}{Ogre} what you’re doing is to use the pass attributes ambient, diffuse, specular and self\+\_\+illumination, just as if you were not using a vertex program. Sure, these attributes do nothing (as far as rendering is concerned) when you’re using vertex programs, but it’s the easiest way to indicate to \hyperlink{namespace_ogre}{Ogre} which light components you’re using in your vertex program. \hyperlink{namespace_ogre}{Ogre} will then classify and potentially split your programmable pass based on this information -\/ it will leave the vertex program as-\/is (so that any split passes will respect any vertex modification that is being done).

Note that when classifying a diffuse/specular programmable pass, \hyperlink{namespace_ogre}{Ogre} checks to see whether you have indicated the pass can be run once per light (iteration once\+\_\+per\+\_\+light). If so, the pass is left intact, including it’s vertex and fragment programs. However, if this attribute is not included in the pass, \hyperlink{namespace_ogre}{Ogre} tries to split off the per-\/light part, and in doing so it will disable the fragment program, since in the absence of the ’iteration once\+\_\+per\+\_\+light’ attribute it can only assume that the fragment program is performing decal work and hence must not be used per light.

So clearly, when you use additive light masking as a shadow technique, you need to make sure that programmable passes you use are properly set up so that they can be classified correctly. However, also note that the changes you have to make to ensure the classification is correct does not affect the way the material renders when you choose not to use additive lighting, so the principle that you should be able to use the same material definitions for all lighting scenarios still holds. Here is an example of a programmable material which will be classified correctly by the illumination pass classifier\+:


\begin{DoxyCode}
\textcolor{comment}{// Per-pixel normal mapping Any number of lights, diffuse and specular}
material Examples/BumpMapping/MultiLightSpecular
\{
    technique
    \{
        \textcolor{comment}{// Base ambient pass}
        pass
        \{
            \textcolor{comment}{// ambient only, not needed for rendering, but as information}
            \textcolor{comment}{// to lighting pass categorisation routine}
            ambient 1 1 1
            diffuse 0 0 0 
            specular 0 0 0 0
            \textcolor{comment}{// Really basic vertex program}
            vertex\_program\_ref \hyperlink{namespace_ogre}{Ogre}/BasicVertexPrograms/AmbientOneTexture
            \{
                param\_named\_auto worldViewProj worldviewproj\_matrix
                param\_named\_auto ambient ambient\_light\_colour
            \}
        \}
        \textcolor{comment}{// Now do the lighting pass}
        \textcolor{comment}{// NB we don't do decal texture here because this is repeated per light}
        pass
        \{
            \textcolor{comment}{// set ambient off, not needed for rendering, but as information}
            \textcolor{comment}{// to lighting pass categorisation routine}
            ambient 0 0 0 
            \textcolor{comment}{// do this for each light}
            iteration once\_per\_light
            scene\_blend add

            \textcolor{comment}{// Vertex program reference}
            vertex\_program\_ref Examples/BumpMapVPSpecular
            \{
                param\_named\_auto lightPosition light\_position\_object\_space 0
                param\_named\_auto eyePosition camera\_position\_object\_space
                param\_named\_auto worldViewProj worldviewproj\_matrix
            \}

            \textcolor{comment}{// Fragment program}
            fragment\_program\_ref Examples/BumpMapFPSpecular
            \{
                param\_named\_auto lightDiffuse light\_diffuse\_colour 0 
                param\_named\_auto lightSpecular light\_specular\_colour 0
            \}

            \textcolor{comment}{// Base bump map}
            texture\_unit
            \{
                texture NMBumpsOut.png
                colour\_op replace
            \}
            \textcolor{comment}{// Normalisation cube map}
            texture\_unit
            \{
                texture nm.png cubic
                tex\_coord\_set 1
                tex\_address\_mode clamp
            \}
            \textcolor{comment}{// Normalisation cube map #2}
            texture\_unit
            \{
                texture nm.png cubic
                tex\_coord\_set 1
                tex\_address\_mode clamp
            \}
        \}

        \textcolor{comment}{// Decal pass}
        pass
        \{
            lighting off
            \textcolor{comment}{// Really basic vertex program}
            vertex\_program\_ref \hyperlink{namespace_ogre}{Ogre}/BasicVertexPrograms/AmbientOneTexture
            \{
                param\_named\_auto worldViewProj worldviewproj\_matrix
                param\_named ambient float4 1 1 1 1
            \}
            scene\_blend dest\_colour zero
            texture\_unit
            \{
                texture RustedMetal.jpg 
            \}
        \}
    \}
\}
\end{DoxyCode}


Note that if you’re using texture shadows you have the additional option of using \href{#Integrated-Texture-Shadows}{\tt Integrated Texture Shadows} rather than being forced to use this explicit sequence -\/ allowing you to compress the number of passes into a much smaller number at the expense of defining an upper number of shadow casting lights. In this case the ’additive’ aspect of the shadow technique just affects the colour of the shadow texture and it’s up to you to combine the shadow textures in your receivers however you like.

\label{_Static-Lighting}%


\subsection*{Static Lighting}

Despite their power, additive lighting techniques have an additional limitation; they do not combine well with pre-\/calculated static lighting in the scene. This is because they are based on the principle that shadow is an absence of light, but since static lighting in the scene already includes areas of light and shadow, additive lighting cannot remove light to create new shadows. Therefore, if you use the additive lighting technique you must either use it exclusively as your lighting solution (and you can combine it with per-\/pixel lighting to create a very impressive dynamic lighting solution), or you must use \href{#Integrated-Texture-Shadows}{\tt Integrated Texture Shadows} to combine the static lighting according to your chosen approach. \hypertarget{Animation}{}\section{Animation}\label{Animation}
O\+G\+RE supports a pretty flexible animation system that allows you to script animation for several different purposes\+:


\begin{DoxyDescription}
\item[\href{#Skeletal-Animation}{\tt Skeletal Animation} ]

Mesh animation using a skeletal structure to determine how the mesh deforms. ~\newline



\item[\href{#Vertex-Animation}{\tt Vertex Animation} ]

Mesh animation using snapshots of vertex data to determine how the shape of the mesh changes.~\newline



\item[\href{#SceneNode-Animation}{\tt Scene\+Node Animation} ]

Animating Scene\+Nodes automatically to create effects like camera sweeps, objects following predefined paths, etc.~\newline



\item[\href{#Numeric-Value-Animation}{\tt Numeric Value Animation} ]

Using O\+G\+R\+E’s extensible class structure to animate any value.


\end{DoxyDescription}\hypertarget{_animation_Skeletal-Animation}{}\subsection{Skeletal Animation}\label{_animation_Skeletal-Animation}
Skeletal animation is a process of animating a mesh by moving a set of hierarchical bones within the mesh, which in turn moves the vertices of the model according to the bone assignments stored in each vertex. An alternative term for this approach is ’skinning’. The usual way of creating these animations is with a modelling tool such as Softimage X\+SI, Milkshape 3D, Blender, 3D Studio or Maya among others. O\+G\+RE provides exporters to allow you to get the data out of these modellers and into the engine See \hyperlink{_mesh-_tools_Exporters}{Exporters}.

There are many grades of skeletal animation, and not all engines (or modellers for that matter) support all of them. O\+G\+RE supports the following features\+:


\begin{DoxyItemize}
\item Each mesh can be linked to a single skeleton
\item Unlimited bones per skeleton
\item Hierarchical forward-\/kinematics on bones
\item Multiple named animations per skeleton (e.\+g. ’\+Walk’, ’\+Run’, ’\+Jump’, ’\+Shoot’ etc)
\item Unlimited keyframes per animation
\item Linear or spline-\/based interpolation between keyframes
\item A vertex can be assigned to multiple bones and assigned weightings for smoother skinning
\item Multiple animations can be applied to a mesh at the same time, again with a blend weighting
\end{DoxyItemize}

~\newline


Skeletons and the animations which go with them are held in .skeleton files, which are produced by the O\+G\+RE exporters. These files are loaded automatically when you create an Entity based on a Mesh which is linked to the skeleton in question. You then use \href{#Animation-State}{\tt Animation State} to set the use of animation on the entity in question.

Skeletal animation can be performed in software, or implemented in shaders (hardware skinning). Clearly the latter is preferable, since it takes some of the work away from the C\+PU and gives it to the graphics card, and also means that the vertex data does not need to be re-\/uploaded every frame. This is especially important for large, detailed models. You should try to use hardware skinning wherever possible; this basically means assigning a material which has a vertex program powered technique. See \href{#Skeletal-Animation-in-Vertex-Programs}{\tt Skeletal Animation in Vertex Programs} for more details. Skeletal animation can be combined with vertex animation, See \href{#Combining-Skeletal-and-Vertex-Animation}{\tt Combining Skeletal and Vertex Animation}.

\label{_Animation-State}%
 \subsection*{Animation State}

When an entity containing animation of any type is created, it is given an ’animation state’ object per animation to allow you to specify the animation state of that single entity (you can animate multiple entities using the same animation definitions, O\+G\+RE sorts the reuse out internally).

You can retrieve a pointer to the Animation\+State object by calling Entity\+::get\+Animation\+State. You can then call methods on this returned object to update the animation, probably in the frame\+Started event. Each Animation\+State needs to be enabled using the set\+Enabled method before the animation it refers to will take effect, and you can set both the weight and the time position (where appropriate) to affect the application of the animation using correlating methods. Animation\+State also has a very simple method ’add\+Time’ which allows you to alter the animation position incrementally, and it will automatically loop for you. add\+Time can take positive or negative values (so you can reverse the animation if you want).\hypertarget{_animation_Vertex-Animation}{}\subsection{Vertex Animation}\label{_animation_Vertex-Animation}
Vertex animation is about using information about the movement of vertices directly to animate the mesh. Each track in a vertex animation targets a single Vertex\+Data instance. Vertex animation is stored inside the .mesh file since it is tightly linked to the vertex structure of the mesh.

There are actually two subtypes of vertex animation, for reasons which will be discussed in a moment.


\begin{DoxyDescription}
\item[\href{#Morph-Animation}{\tt Morph Animation} ]

Morph animation is a very simple technique which interpolates mesh snapshots along a keyframe timeline. Morph animation has a direct correlation to old-\/school character animation techniques used before skeletal animation was widely used.~\newline



\item[\href{#Pose-Animation}{\tt Pose Animation} ]

Pose animation is about blending multiple discrete poses, expressed as offsets to the base vertex data, with different weights to provide a final result. Pose animation’s most obvious use is facial animation.


\end{DoxyDescription}\label{_Why-two-subtypes_003f}%


\subsection*{Why two subtypes?}

So, why two subtypes of vertex animation? Couldn’t both be implemented using the same system? The short answer is yes; in fact you can implement both types using pose animation. But for very good reasons we decided to allow morph animation to be specified separately since the subset of features that it uses is both easier to define and has lower requirements on hardware shaders, if animation is implemented through them. If you don’t care about the reasons why these are implemented differently, you can skip to the next part.

Morph animation is a simple approach where we have a whole series of snapshots of vertex data which must be interpolated, e.\+g. a running animation implemented as morph targets. Because this is based on simple snapshots, it’s quite fast to use when animating an entire mesh because it’s a simple linear change between keyframes. However, this simplistic approach does not support blending between multiple morph animations. If you need animation blending, you are advised to use skeletal animation for full-\/mesh animation, and pose animation for animation of subsets of meshes or where skeletal animation doesn’t fit -\/ for example facial animation. For animating in a vertex shader, morph animation is quite simple and just requires the 2 vertex buffers (one the original position buffer) of absolute position data, and an interpolation factor. Each track in a morph animation references a unique set of vertex data.

Pose animation is more complex. Like morph animation each track references a single unique set of vertex data, but unlike morph animation, each keyframe references 1 or more ’poses’, each with an influence level. A pose is a series of offsets to the base vertex data, and may be sparse -\/ i.\+e. it may not reference every vertex. Because they’re offsets, they can be blended -\/ both within a track and between animations. This set of features is very well suited to facial animation.

For example, let’s say you modelled a face (one set of vertex data), and defined a set of poses which represented the various phonetic positions of the face. You could then define an animation called ’\+Say\+Hello’, containing a single track which referenced the face vertex data, and which included a series of keyframes, each of which referenced one or more of the facial positions at different influence levels -\/ the combination of which over time made the face form the shapes required to say the word ’hello’. Since the poses are only stored once, but can be referenced may times in many animations, this is a very powerful way to build up a speech system.

The downside of pose animation is that it can be more difficult to set up, requiring poses to be separately defined and then referenced in the keyframes. Also, since it uses more buffers (one for the base data, and one for each active pose), if you’re animating in hardware using vertex shaders you need to keep an eye on how many poses you’re blending at once. You define a maximum supported number in your vertex program definition, via the includes\+\_\+pose\+\_\+animation material script entry, See \hyperlink{_high-level-_programs_Pose-Animation-in-Vertex-Programs}{Pose Animation in Vertex Programs}.

So, by partitioning the vertex animation approaches into 2, we keep the simple morph technique easy to use, whilst still allowing all the powerful techniques to be used. Note that morph animation cannot be blended with other types of vertex animation on the same vertex data (pose animation or other morph animation); pose animation can be blended with other pose animation though, and both types can be combined with skeletal animation. This combination limitation applies per set of vertex data though, not globally across the mesh (see below). Also note that all morph animation can be expressed (in a more complex fashion) as pose animation, but not vice versa.

\label{_Subtype-applies-per-track}%


\subsection*{Subtype applies per track}

It’s important to note that the subtype in question is held at a track level, not at the animation or mesh level. Since tracks map onto Vertex\+Data instances, this means that if your mesh is split into Sub\+Meshes, each with their own dedicated geometry, you can have one Sub\+Mesh animated using pose animation, and others animated with morph animation (or not vertex animated at all).

For example, a common set-\/up for a complex character which needs both skeletal and facial animation might be to split the head into a separate Sub\+Mesh with its own geometry, then apply skeletal animation to both submeshes, and pose animation to just the head.

To see how to apply vertex animation, See \href{#Animation-State}{\tt Animation State}.

\label{_Vertex-buffer-arrangements}%


\subsection*{Vertex buffer arrangements}

When using vertex animation in software, vertex buffers need to be arranged such that vertex positions reside in their own hardware buffer. This is to avoid having to upload all the other vertex data when updating, which would quickly saturate the G\+PU bus. When using the O\+G\+RE .mesh format and the tools / exporters that go with it, O\+G\+RE organises this for you automatically. But if you create buffers yourself, you need to be aware of the layout arrangements.

To do this, you have a set of helper functions in \hyperlink{class_ogre_1_1_mesh}{Ogre\+::\+Mesh}. See A\+PI Reference entries for \hyperlink{class_ogre_1_1_vertex_data_a106603d9d4d6c2f6e0d5eb6c25eb7c32}{Ogre\+::\+Vertex\+Data\+::reorganise\+Buffers()} and \hyperlink{class_ogre_1_1_vertex_declaration_a130fa715330d23d0e9d2feef630b460c}{Ogre\+::\+Vertex\+Declaration\+::get\+Auto\+Organised\+Declaration()}. The latter will turn a vertex declaration into one which is recommended for the usage you’ve indicated, and the former will reorganise the contents of a set of buffers to conform to that layout.

\label{_Morph-Animation}%
 \label{_Morph-Animation-1}%


\subsection*{Morph Animation}

Morph animation works by storing snapshots of the absolute vertex positions in each keyframe, and interpolating between them. Morph animation is mainly useful for animating objects which could not be adequately handled using skeletal animation; this is mostly objects that have to radically change structure and shape as part of the animation such that a skeletal structure isn’t appropriate.

Because absolute positions are used, it is not possible to blend more than one morph animation on the same vertex data; you should use skeletal animation if you want to include animation blending since it is much more efficient. If you activate more than one animation which includes morph tracks for the same vertex data, only the last one will actually take effect. This also means that the ’weight’ option on the animation state is not used for morph animation.

Morph animation can be combined with skeletal animation if required See \href{#Combining-Skeletal-and-Vertex-Animation}{\tt Combining Skeletal and Vertex Animation}. Morph animation can also be implemented in hardware using vertex shaders, See \href{#Morph-Animation-in-Vertex-Programs}{\tt Morph Animation in Vertex Programs}.

\label{_Pose-Animation}%
 \label{_Pose-Animation-1}%


\subsection*{Pose Animation}

Pose animation allows you to blend together potentially multiple vertex poses at different influence levels into final vertex state. A common use for this is facial animation, where each facial expression is placed in a separate animation, and influences used to either blend from one expression to another, or to combine full expressions if each pose only affects part of the face.

In order to do this, pose animation uses a set of reference poses defined in the mesh, expressed as offsets to the original vertex data. It does not require that every vertex has an offset -\/ those that don’t are left alone. When blending in software these vertices are completely skipped -\/ when blending in hardware (which requires a vertex entry for every vertex), zero offsets for vertices which are not mentioned are automatically created for you.

Once you’ve defined the poses, you can refer to them in animations. Each pose animation track refers to a single set of geometry (either the shared geometry of the mesh, or dedicated geometry on a submesh), and each keyframe in the track can refer to one or more poses, each with its own influence level. The weight applied to the entire animation scales these influence levels too. You can define many keyframes which cause the blend of poses to change over time. The absence of a pose reference in a keyframe when it is present in a neighbouring one causes it to be treated as an influence of 0 for interpolation.

You should be careful how many poses you apply at once. When performing pose animation in hardware (See \mbox{[}Pose Animation in Vertex Programs\mbox{]}(@ ref Pose-\/\+Animation-\/in-\/\+Vertex-\/\+Programs)), every active pose requires another vertex buffer to be added to the shader, and in when animating in software it will also take longer the more active poses you have. Bear in mind that if you have 2 poses in one keyframe, and a different 2 in the next, that actually means there are 4 active keyframes when interpolating between them.

You can combine pose animation with skeletal animation, See \href{#Combining-Skeletal-and-Vertex-Animation}{\tt Combining Skeletal and Vertex Animation}, and you can also hardware accelerate the application of the blend with a vertex shader, See \hyperlink{_high-level-_programs_Pose-Animation-in-Vertex-Programs}{Pose Animation in Vertex Programs}.

\label{_Combining-Skeletal-and-Vertex-Animation}%
 \label{_Combining-Skeletal-and-Vertex-Animation-1}%


\subsection*{Combining Skeletal and Vertex Animation}

Skeletal animation and vertex animation (of either subtype) can both be enabled on the same entity at the same time (See \href{#Animation-State}{\tt Animation State}). The effect of this is that vertex animation is applied first to the base mesh, then skeletal animation is applied to the result. This allows you, for example, to facially animate a character using pose vertex animation, whilst performing the main movement animation using skeletal animation.

Combining the two is, from a user perspective, as simple as just enabling both animations at the same time. When it comes to using this feature efficiently though, there are a few points to bear in mind\+:


\begin{DoxyItemize}
\item \href{#Combined-Hardware-Skinning}{\tt Combined Hardware Skinning}
\item \href{#Submesh-Splits}{\tt Submesh Splits}
\end{DoxyItemize}

\label{_Combined-Hardware-Skinning}%
\label{_Combined-Hardware-Skinning-1}%


\subsection*{Combined Hardware Skinning}

For complex characters it is a very good idea to implement hardware skinning by including a technique in your materials which has a vertex program which can perform the kinds of animation you are using in hardware. See \hyperlink{_high-level-_programs_Skeletal-Animation-in-Vertex-Programs}{Skeletal Animation in Vertex Programs}, \hyperlink{_high-level-_programs_Morph-Animation-in-Vertex-Programs}{Morph Animation in Vertex Programs}, \hyperlink{_high-level-_programs_Pose-Animation-in-Vertex-Programs}{Pose Animation in Vertex Programs}.

When combining animation types, your vertex programs must support both types of animation that the combined mesh needs, otherwise hardware skinning will be disabled. You should implement the animation in the same way that O\+G\+RE does, i.\+e. perform vertex animation first, then apply skeletal animation to the result of that. Remember that the implementation of morph animation passes 2 absolute snapshot buffers of the from \& to keyframes, along with a single parametric, which you have to linearly interpolate, whilst pose animation passes the base vertex data plus ’n’ pose offset buffers, and ’n’ parametric weight values.

\label{_Submesh-Splits}%
\label{_Submesh-Splits-1}%


\subsection*{Submesh Splits}

If you only need to combine vertex and skeletal animation for a small part of your mesh, e.\+g. the face, you could split your mesh into 2 parts, one which needs the combination and one which does not, to reduce the calculation overhead. Note that it will also reduce vertex buffer usage since vertex keyframe / pose buffers will also be smaller. Note that if you use hardware skinning you should then implement 2 separate vertex programs, one which does only skeletal animation, and the other which does skeletal and vertex animation.\hypertarget{_animation_SceneNode-Animation}{}\subsection{Scene\+Node Animation}\label{_animation_SceneNode-Animation}
Scene\+Node animation is created from the Scene\+Manager in order to animate the movement of Scene\+Nodes, to make any attached objects move around automatically. You can see this performing a camera swoop in Demo\+\_\+\+Camera\+Track, or controlling how the fish move around in the pond in Demo\+\_\+\+Fresnel.

At it’s heart, scene node animation is mostly the same code which animates the underlying skeleton in skeletal animation. After creating the main Animation using Scene\+Manager\+::create\+Animation you can create a Node\+Animation\+Track per Scene\+Node that you want to animate, and create keyframes which control its position, orientation and scale which can be interpolated linearly or via splines. You use \href{#Animation-State}{\tt Animation State} in the same way as you do for skeletal/vertex animation, except you obtain the state from Scene\+Manager instead of from an individual Entity.\+Animations are applied automatically every frame, or the state can be applied manually in advance using the \+\_\+apply\+Scene\+Animations() method on Scene\+Manager. See the A\+PI reference for full details of the interface for configuring scene animations.\hypertarget{_animation_Numeric-Value-Animation}{}\subsection{Numeric Value Animation}\label{_animation_Numeric-Value-Animation}
Apart from the specific animation types which may well comprise the most common uses of the animation framework, you can also use animations to alter any value which is exposed via the \href{#AnimableObject}{\tt Animable\+Object} interface.

\label{_AnimableObject}%
\label{_AnimableObject-1}%


\subsection*{Animable\+Object}

Animable\+Object is an abstract interface that any class can extend in order to provide access to a number of \href{#AnimableValue}{\tt Animable\+Value}s. It holds a ’dictionary’ of the available animable properties which can be enumerated via the get\+Animable\+Value\+Names method, and when its create\+Animable\+Value method is called, it returns a reference to a value object which forms a bridge between the generic animation interfaces, and the underlying specific object property.

One example of this is the Light class. It extends Animable\+Object and provides Animable\+Values for properties such as \char`\"{}diffuse\+Colour\char`\"{} and \char`\"{}attenuation\char`\"{}. Animation tracks can be created for these values and thus properties of the light can be scripted to change. Other objects, including your custom objects, can extend this interface in the same way to provide animation support to their properties.

\label{_AnimableValue}%
\label{_AnimableValue-1}%


\subsection*{Animable\+Value}

When implementing custom animable properties, you have to also implement a number of methods on the Animable\+Value interface -\/ basically anything which has been marked as unimplemented. These are not pure virtual methods simply because you only have to implement the methods required for the type of value you’re animating. Again, see the examples in Light to see how this is done. 