@c -*-texinfo-*-
@node FAQ, Release Notes, Glossary, Top
@appendix Frequently Asked Questions (@sc{faq})
@cindex Frequently Asked Questions
@cindex @sc{faq}

This is a list of frequently asked questions and their answers.  If you have
some questions about Crystal Space, try consulting this list first.

The first section contains practical questions and answers.  The second
section (see later) contains more technical questions.

More @sc{faq}s can also be found online in the Crystal Space Wiki:@*

@noindent
@uref{http://www.crystalspace3d.org/main/FAQ}

@itemize @bullet
@item
@strong{Q}: From where can I download Crystal Space?

@strong{A}: The latest release of Crystal Space is always available from the
Crystal Space home page, and from the Crystal Space download site:

@noindent
@uref{http://www.crystalspace3d.org/downloads/release/}

@noindent
You can also access the bleeding-edge developmental version.
@xref{Where to Get}.

@item
@strong{Q}: What do I need to compile Crystal Space?

@strong{A}: You need the source code, which you can obtain in a variety of
ways.  @xref{Where to Get}.  You also need a compiler and development system
for the platform which you are using.  Some of the supported compilers are
@sc{gcc} (including MingW and Cygwin), @sc{msvc} and Code Warrior.

@item
@strong{Q}: What do you need to run Crystal Space?

@strong{A}: You need the following items:

@itemize @minus
@item
A compiled executable program such as @file{walktest} or @file{csdemo}, for
example.  These are demo programs included in the main source archive.

Note that there exist two types of executables: statically linked and
dynamically linked.  If you have a statically linked executable then you don't
need any of the following drivers.  Otherwise you will need the remaining
items.

@item
Several plugins for those applications.  On and Windows (32 bit) plugins
will be @file{.DLL} files.  On most Unix systems they will be @file{.so} files.
 If Crystal Space compiled successfully then you will have a great deal of
those plugins in the Crystal Space directory.

@item
You should also have the data directory which is included with Crystal
Space.  This directory contains various texture and data libraries (like
@file{standard.zip}), data files for some of the applications (like
the @samp{castle} world file for @file{walktest}), 
shader definitions, configuration files for various plugins in Crystal Space
and a lot more.

@item
Crystal Space applications also require a @file{vfs.cfg} configuration file
which tells the virtual file system (@sc{vfs}) where everything is located.

@item
In addition to maps that are included in the data folder of Crystal Space
itself (@samp{castle}, @samp{flarge}, @samp{partsys}, @samp{terrainf}, @dots{})
you can also download additional maps for @file{walktest}.  The map files
included with Crystal Space are normal directories but Crystal Space can
also read directly from @sc{zip} archives.
@end itemize

@item
@strong{Q}: I downloaded Crystal Space but it won't run.  What could be the
cause?

@strong{A1}: Are you sure that you have downloaded all the necessary
components, as explained by the previous section? If not, then download the
missing components.

@strong{A2}: In general, Crystal Space requires a 15, 16, or 32-bit
display and will not work with other displays modes.  Note, however, that the
Mac OS X Server, OpenStep, and NextStep ports of Crystal Space are not subject
to this limitation.

@strong{A3}: If you are using a dynamically linked executable then the required
plug-in modules, such as 3D renderer, 2D driver, etc., usually must reside in
the same directory.  On Mac OS X, the plug-in modules can reside in a
@file{components} subdirectory.  Most ports of Crystal Space use plug-in
modules by default.

@strong{A4}: Are you certain that you are trying to load the correct map file?
If you are running the application from the command-line, then you can try
specifying the map file on on the command-line, like this:

@example
% walktest flarge
@end example

Where @samp{flarge} is the name of the map file you wish to use.  In this case,
@samp{flarge} corresponds to the @file{flarge} directory which is included
with @samp{cs}.  Also note that @samp{flarge} itself requires the file
@file{standard.zip} which contains all the textures.

Alternately, for WalkTest, you can change the @samp{WorldFile} setting in its
configuration file @file{CS/data/config-apps/walktest.cfg}.  For example:

@example
Walktest.Settings.WorldFile = flarge
@end example

@strong{A5}: If all else fails ask a question on the Crystal Space mailing
list.  @xref{Mailing Lists}.

@item
@strong{Q}: What documentation is available?  Where can I find it?

@strong{A}: There is a lot of documentation available.  Not all of it is
completely up-to-date but we try to do our best in keeping it as up-to-date as
possible.  Refer to the section in the Crystal Space manual which discusses
documentation resources.  @xref{Documentation Resources}.

@item
@strong{Q}: I'm using OpenGL with Crystal Space (via the @samp{-video=opengl}
command-line option, for example) and the animation is extremely slow.  What's
wrong?

@strong{A1}: When this happens this usually means that your OpenGL renderer
is not using hardware acceleration. If you are sure that you actually have
a 3D card that is supported by OpenGL then you should make sure you have
recent drivers for that card and that they are properly configured.

@strong{A2}: Note that some operations in Crystal Space require the
existence of a stencil buffer. If there is no hardware stencil available
OpenGL will revert to using software which is very slow. Some 3D cards
only have hardware stencil in some display modes. For example ATI and
nVidia cards only have accelerated stencil in 24/32-bit color mode and
not in 16-bit mode.

@item
@strong{Q}: I want to create textures for Crystal Space.  What palette should I
use?  How big should I create the textures?  What format can I use?

@strong{A1}: The palette does not really matter because Crystal Space
calculates its own optimal palette given a set of input textures.  But there
are some things to keep in mind.  Try to get the number of different colours as
low as possible without sacrificing for quality and if you design a set of
textures that are meant to be used together it is always best to let them use
a similar palette.  This will make it easier for Crystal Space to calculate a
good palette.

@strong{A2}: The width and height of a texture must be a power of 2 (such as
8, 16, 32, 64, @dots{}).  That's about the only restriction.  Textures need
not be square.  You can have textures with sizes like 16x256. If a texture
does not conform to the above mentioned limitations then it will be scaled.
This may mean that there is quality degradation though!

@strong{A3}: Crystal Space textures may be in any of the supported image
formats, such as @sc{png}, @sc{tga}, @sc{bmp}, @sc{jpg}, @sc{mng} and @sc{gif}.

@strong{A4}: Unless a texture is not meant for tiling you should make sure
that it can be tiled.  This means that if you put a number of textures next to
each other or above each other the boundaries should seamlessly integrate with
each other.  Of course, it is entirely possible to create textures that are
specifically drawn for untiled usage.  An example would be a texture
representing a computer keyboard.

@item
@strong{Q}: How can I actually make 3D models and maps for use in Crystal
Space?

@strong{A1}: You can use Blender (@uref{http://www.blender3d.org/})
together with blender2crystal
(aka. b2cs, @uref{http://b2cs.delcorp.org/}).  blender2crystal works
very well and is fully supported by the Crystal Space project.  Using this
convertor you can make complete maps with support for portals and much more.
It also supports @samp{AniMesh} models.

@strong{A2}: For animated models using Cal3D (@pxref{MeshObject SprCal3D})
you can also use Blender, which has support for Cal3D objects.
There is a tutorial on this subject at:

@noindent
@uref{http://www.cs.indiana.edu/~joellis/CSIntro.html}

@strong{A3}: For maps and objects using @samp{genmesh}
you can also use 3dsMax.  There is a 3dsMax exporter plugin
included with Crystal Space (@file{CS/scripts/max}) with associated
documentation which works very well.  This script is made and used by the 
PlaneShift project (@uref{http://www.planeshift.it}). There is a tutorial
on this exporter at:

@noindent
@uref{http://www.crystalspace3d.org/docs/online/maxexporter/}

@strong{A4}: For animated models using Cal3D you can also use
3dsMax.  There is a tutorial on this subject at:

@noindent
@uref{http://cal3d.sourceforge.net/modeling/tutorial.html}

@strong{A5}: There is a tool to convert map files (from tools like
Q3Radiant, Hammer, or QuArK) to @sc{cs}. You can find this tool at:

@noindent
@uref{http://www-poleia.lip6.fr/~degris/converter/}

@strong{A6}: There is a @file{Maya2Spr} utility included with Crystal Space
which can convert Maya files to 3D sprites. Not for maps, though.

@strong{A7}: There is a @file{3ds2lev} utility to convert @file{.3ds} files
to either a level or a 3D sprite model.  This tool is very limited though
and the generated maps usually require hand-editing.

@strong{A8}: There is @file{md22spr} utility which can convert Quake @sc{md2}
and @sc{mdl} models to Crystal Space 3D sprites. The animation frames are also
properly converted.  This will not generate Cal3D models!

@strong{A9}: There is md32spr utility which can convert Quake @sc{md3} models.

@item
@strong{Q}: I would like to contribute to Crystal Space.  What can I do?

@strong{A}: Have a look at the section of this manual about contributing
to the project (@pxref{Contributing}), and take a look at the To-Do and
Bug lists on the Developer's Project page at SourceForge:

@noindent
@uref{http://sourceforge.net/projects/crystal/}

@noindent You can also contact the mailing list (@pxref{Mailing Lists}) in
order to coordinate your efforts with those of other people.

@item
@strong{Q}: How does Crystal Space work?

@strong{A1} If you want to know how you can use @sc{cs}, you can look at the
@xref{Using Crystal Space}. If you want to know how
it works internally, @xref{Internals}.

@strong{A2}: Read any other documentation related to this project as mentioned
earlier in this @sc{faq}.

@strong{A3}: If you need more information, you should consider posting your
queries to the Crystal Space mailing list, @ref{Mailing Lists}.

@item
@strong{Q}: I want to write a game with Crystal Space.  Can I do this?

@strong{A1}: The ultimate purpose of Crystal Space is that it will become a
usable and powerful engine for writing games and other graphics visualization
programs.  As a project which is still under development, it may be simple or
difficult to build your particular game, depending upon your specific
requirements.  One way to improve the state of Crystal Space so that it better
fits your needs is to contribute to the project yourself.

@strong{A2}: Crystal Space is under the @sc{lgpl} licensing policy so you can
make commercial or shareware products using it.  For more details about what
you can and cannot do, see the license, @ref{Licenses}.

@item
@strong{Q}: How stable is the @sc{api} for Crystal Space?

@strong{A}: Between every subsequence stable release (for example, from 1.0
to 1.2 or from 1.2 to 1.4) we always try to guarantee backwards compatibility.
If we want to remove some feature we will @samp{deprecate} it. When something
is deprecated in version 1.2 (for example) then it means that it will probably
be removed in 1.4. So make sure to change your applications to avoid using
the deprecated stuff.

In the future 2.0 release we plan more significant changes for which we will no
longer be able to guarantee backwards compatibility.
@end itemize

The following section lists some more technical questions.

@itemize @bullet
@item
@strong{Q}: I have some objects but collision detection is not working on
them. What is wrong?

@strong{A}: One of the most common errors is to scale an object using
the transform in the movable. Unfortunately various subsystems in Crystal
Space (like collision detection and visibility culling) don't work on
scaled objects. If you want to scale your object you should do it
with @code{HardTransform} or @code{<hardmove>} instead. Note that for
some types of mesh objects (like 3D sprites) you must do this on the factory.

@item
@strong{Q}: I have some objects that seem to be culled wrong. What can cause
this?

@strong{A1}: See the question about collision detection not working with
scaled objects. Don't scale your objects using the movable. Instead scale
them with @code{HardTransform}.

@strong{A2}: Another common error is forgetting to call
@code{movable->UpdateMove()} after moving a model. If you don't call that
function then the visibility culler doesn't know the object has moved.

@item
@strong{Q}: I'm confused by the Crystal Space coordinate system.  The 3D
renderer seems to work in reverse y.  What's up?

@strong{A}: When talking in 3D, Crystal Space defines the positive X axis
as pointing to the right, the positive Y axis as pointing upwards, and
the positive Z axis pointing forwards.  2D operations in the 3D renderer
(like when drawing polygons using coordinates perspective projected by
the engine) work with positive X axis to the right (as usual), and positive
Y axis pointing upwards (so (0,0) is in the bottom-left corner).  This is the
exact reverse of how screen coordinates are usually defined but corresponds
better with the Y axis pointing upwards in 3D coordinates).
However, when getting mouse events the normal screen
space coordinate system is used with (0,0) in the top-left corner.

@item
@strong{Q}: Why can't I get the
@code{iGeneralMeshState} / @code{iSprite3DState} / @dots{} from my mesh wrapper?  I
do @code{scfQueryInterface} from the mesh and it returns @samp{0}.

@strong{A}: A common error is to try to query the state interface for
a mesh object from the @code{iMeshWrapper} instance.  However it is not
@code{iMeshWrapper} that represents the mesh object.  @code{iMeshWrapper} is
only a stub in the engine to wrap a mesh object so the engine can use
it.  To get the state interface you must query from the @code{iMeshObject}
instance instead.  You can get this instance with @code{mesh->GetMeshObject()}.

@item
@strong{Q}: I do not understand when I have to use @code{DecRef()} and when
not.  Can you explain this reference counting to me?

@strong{A}: In recent versions of Crystal Space we now have a new
@code{csRef} class which implements a kind of smart pointer.  Smart pointers
make it easier for you to keep track of references.  They will automatically
@code{DecRef()} when they are ready.  Here is an example of their usage:

@example
csRef<iGeneralMeshState> st =
  scfQueryInterface<iGeneralMeshState> (mesh->GetMeshObject());
if (st)
@{
  st->blabla @dots{};
@}
@end example

You can use the @samp{st} variable just like you would use the normal
@code{iGeneralMeshState} reference. The only difference with code that doesn't use
smart pointers is that you don't have to take care of calling
@code{DecRef}.  @xref{Smart Pointers}.

@item
@strong{Q}: My objects are rendered incorrectly.  It seems as if parts of it
sometimes appear and sometimes disappear.

@strong{A}: Incorrect rendering of objects can be caused by bugs but there
is one common cause of this problem which is Z-buffer related.  It is
important to realize that Crystal Space does @sc{not} clear the Z-buffer
every frame (nor does it clear the screen).  By default Crystal Space depends
on the geometry itself to clear the Z-buffer.  For example, if you have a
room with a single object in it then you should use @samp{ZFILL} mode for
the room polygons (so that the Z-buffer will be filled but not read) and
@samp{ZUSE} for the object (so that the Z-buffer will be both
updated and read).

In many cases levels are closed (meaning that there is some exterior object
which blocks the view into infinity). If you have such a convex closed
object at the boundary of your level you can use @samp{ZFILL} for that.
However, there are occasions when this is not possible.  Either because there
is no exterior object, the exterior object is not closed, or the exterior
object is not convex.  In that case you better use @samp{ZUSE} for all objects
and enable Z-clearing every frame. In world files you can do this by
using the @samp{settings} block and enabling the @samp{clearzbuf} option.

Note that you should invoke the method @code{engine->GetBeginDrawFlags()} in
your call to @code{g3d->BeginDraw()} to ensure that this Z-buffer clearing will
actually work (in fact you should @emph{always} use
@code{GetBeginDrawFlags()}).

@item
@strong{Q}: I'm trying to use some plugin but it says that it cannot find it
(i.e. @code{csQueryRegistry} returns null).

@strong{A}: It is important to realize that @code{csQueryRegistry}
does @samp{not} load a plugin.  It only looks for some component in the object
registry.  There are two basic ways to load a plugin: the first is to use
@code{csInitializer::RequestPlugins()} and the second is to manually
load the plugin using @code{csLoadPlugin}.  @code{RequestPlugins()} is
best because it actually registers the plugin with the object
registry and it also correctly manages config file, command-line and
request plugins (so you can override a plugin on command-line/config file).

@item
@strong{Q}: How can I show @sc{fps} (Frames Per Second) in my Crystal Space
application?

@strong{A}: Add the following entry to the user-specific application-neutral
or application-specific domain (@pxref{Configuration File}):

@example
Global.System.Plugins.iBugPlug = crystalspace.utilities.bugplug
@end example

This will make sure that the BugPlug plugin runs in either you or any 
Crystal Space application (dependent on the config domain you chose). 
BugPlug shows @sc{fps} (among other things) and is otherwise not harmful.  You
can also use BugPlug to make screen-shots (press @kbd{Ctrl-d} followed by
@kbd{F12}). @xref{BugPlug}.

@end itemize
