@c -*-texinfo-*-
@node Glossary, FAQ, Contributing, Top
@appendix Glossary
@cindex Glossary

This is a short glossary of terminology used throughout the documentation as
well as in discussions of 3D graphics.

@table @emph
@item 3D Renderer
The 3D renderer plugin in Crystal Space is responsible for rendering
3D objects (polygons) on the canvas.  We have several renderers but the two
most common are the software and OpenGL renderers.

@item 3D Sprite
A 3D Sprite in Crystal Space is a mesh object based on a triangle mesh.
It is often used for actors.  The word @samp{Sprite} may be confusing because
a 3D Sprite is really a full 3D object.  3D Sprites support frame based
animation.  The @sc{sprcal3d} mesh object also supports skeletal animation
through the Cal3d library.

@item Ambient (lighting)
Ambient lighting is a constant amount of lighting that is added to all other
lighting.

@item Camera Space
Before viewing objects and rooms are transformed from world to camera space.
This means that the position of the camera is set at (0,0,0); the positive z
direction points away from the eyes, the y direction is up and the x
direction is right.

@item Canvas
A canvas is a plugin which is responsible for managing a window for
Crystal Space.  On operating systems that don't support windows the canvas
will represent the screen.  The 3D renderer will use a canvas to render on.

@item Detail Texture
A detail texture is a texture that is blended on top of another texture
so that the texture gets more detail.  Crystal Space supports this by
allowing several detail layers on top of the base texture in a material.

@item Event Queue
Crystal Space is an event-driven framework.  So a Crystal Space application
will also be event driven. The event queue manages the event system and
sends events to listeners.  Every module or plugin that implements
@code{iEventHandler} can register itself with the event queue so it gets
notified when certain events happen. See also with
@code{csInitializer::CreateEventQueue()} or
@code{csInitializer::CreateEnvironment()}.

@item Haze Mesh Object
A haze mesh object is a bit like volumetric light.  It represents a 3D
volume on which a texture is applied in a fuzzy way.

@item Light-Map Space
Two-dimensional (l,m) coordinate-system corresponding to some point on a
light-map.  Light-map space is closely related to texture space.

@item Lumel
A lumel is a pixel on a lightmap.  A lumel corresponds with one light
value (red, green, blue) and represents the lighting values of a block of
texels on the original texture.  Usually this block is 16x16 big.

@item Material
A material represents how some object or polygon looks.  In the most common
case a material is just a texture. But a material can contain additional
information like detail textures (textures that are blended on top of
the base texture).  In future materials will be able to do much more.

@item Mesh Factory
A mesh factory is an object from which you can create mesh objects.
@xref{MeshObject}.

@item Mesh Object
A mesh object represents geometry in Crystal Space.  The Crystal Space engine
is very modular.  The engine itself does not know how to render.  It only
knows about mesh objects.  Every mesh object is responsible for rendering
what it represents (using the 3D renderer).  Crystal Space supports several
mesh objects: things, 3D sprites, 2D sprites, particle systems, haze,
terrain engine, @dots{}

@item Object Registry
The object registry (represented by the @code{iObjectRegistry} interface
is the central repository for all objects in Crystal Space.  Everything in
Crystal Space will use the object registry to get the pointer to the objects
it is interested in.  See also:

@noindent
@code{csInitializer::CreateObjectRegistry()}@*
@code{csInitializer::CreateEnvironment()}

@item Object Space
Every object or room is defined with its own local 3D coordinate system
typically centered around (0,0,0).

@item Particle System
A particle system is another kind of mesh object.  Crystal Space supports
several particle systems (snow, rain, fire, explosion, emit, ...).

@item Plugin
A plugin is a number of classes that can be loaded dynamically into
a running Crystal Space application.  A plugin is represented by a dynamic
library in a format suitable for the host operating system.  On Unix like
systems this is a @file{.so} file and on Windows systems this is a
@file{.dll} file.

@item Plugin Manager
The plugin manager is responsible for loading and unloading plugins.  A
plugin is a shared library of functions that can be loaded dynamically
into a running Crystal Space application.  On Unix a plugin has the
@file{.so} extension and on Windows the @file{.dll} extension is
used.  Almost everything in the Crystal Space framework is itself a
plugin.  So the plugin manager is an important object.  See also
@code{csInitializer::CreatePluginManager()} or
@code{csInitializer::CreateEnvironment()}.

@item Portal
A Portal is one of the polygons of a thing mesh object which will not be
texture mapped (unless it has a semi-transparent texture).  Instead another
sector (visible through that portal) will be drawn.  A portal may
even point back into the sector in which it is contained.  This is
useful for portals which act as mirrors.  A more general form of a mirror
is a space warping portal.  This way a portal can go to any place in the
world.

@item Procedural Texture
A procedural texture is a special texture that has a 3D renderer
associated with it.  This means that you can change the image on the
procedural texture by drawing on it.  Since the procedural texture
has a full 3D renderer associated with it you can even use the 3D
engine to render on a texture.  Procedural textures can be used on
all objects in Crystal Space that can use textures.

@item Region
A region in Crystal Space is a collection of objects (textures, materials,
mesh objects, mesh factories, sectors, sequences, triggers, shared variables,
collections, @dots{}).  Regions are not a geometrical concept.  It is possible
to define a region which contains all wall geometry and a region which
contains all moving geometry.  Usually though, regions represent some area
in the world.  You can use regions to dynamically load/unload parts of the
world.  This is useful if you have really big worlds that don't fit in
memory at once.

@item Reporter
The reporter is a plugin in Crystal Space that listens to messages.
It supports the notion of errors, warnings, and notification messages.
All components in Crystal Space use the reporter to report about unusual
situations.  An application can be aware of the reporter in two ways:
it can either query the messages at regular intervals or else it can
install a @dfn{reporter listener}.  There is also a standard reporter
listener plugin in Crystal Space which will use the console to output
notification messages and use other means to report errors.

@item Reporter Listener
A reporter listener in general is an entity that can register itself
with a reporter to listen to message that arrive on that reporter.
There is also a standard reporter listener plugin that you can use
so you don't need to write your own reporter listener.

@item @sc{scf}
The shared class facility.  A mechanism for managing plugin modules and
treating objects in a uniform manner. Also manages reference counting.
@xref{SCF}.

@item Screen Space
Two-dimensional coordinate-system corresponding to physical screen coordinates.
Screen space is perspective corrected camera space.

@item Sector
A sector is simply a container of geometry.  It contains several mesh objects
which will represent the geometry of the sector.  A common mesh object is
the thing mesh object which is usually used to put walls around a sector
(that way the sector represents a room).  Other mesh objects like 3d sprites
can be used for actors.

@item Texel
A texel is a pixel on a texture.  For example, an 128x128 texture has
128x128 texels.  On screen this may result in more or fewer pixels depending
on how far away the object is on which the texture is used and also on how
the texture is scaled on the object.

@item Texture Space
Two-dimensional (u,v) coordinate-system corresponding to some point on a
texture.  Texture space is given by a transformation matrix and vector going
from object space to texture space.

@item Thing Mesh Object
A mesh object which is often used to represent walls of a sector but can
in general be used to represent many more kinds of objects.

@item Virtual Clock
Most Crystal Space applications will be time-based.  The virtual clock
supports the notion of @sc{current time} and @sc{elapsed time}.  It is
called a virtual clock because it doesn't necessarily have to correspond
with real time.  A game can be paused for example.  Note that a well-behaved
game should always take elapsed time (between two frames) into consideration
for calculating what could have happened in that time.  This is important
especially for physics calculations and also for speed of moving objects.
You want an object moving at some speed to move with the same speed on a
system with low framerates compared to a system with high framerates.
See also @code{csInitializer::CreateVirtualClock()} or
@code{csInitializer::CreateEnvironment()}.

@item World Space
Three-dimensional coordinate-system corresponding to the world in which all
objects live.  Mesh objects are mapped from object space to world space via a
matrix transformation.

@item @sc{vfs}
The virtual file system.  A mechanism for unifying filesystem access between
various platforms. Using this a Crystal Space application can read and write
transparently from @sc{zip} archives. @xref{VFS}.
@end table
