Crystal Space 2.0.0: B. Frequently Asked Questions (FAQ)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# B. Frequently Asked Questions (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 FAQs can also be found online in the Crystal Space Wiki:

http://www.crystalspace3d.org/main/FAQ

- Q: From where can I download Crystal Space?

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

  http://www.crystalspace3d.org/downloads/release/

  You can also access the bleeding-edge developmental version. See section Where to Get Crystal Space.

- Q: What do I need to compile Crystal Space?

  A: You need the source code, which you can obtain in a variety of ways. See section Where to Get Crystal Space. You also need a compiler and development system for the platform which you are using. Some of the supported compilers are GCC (including MingW and Cygwin), MSVC and Code Warrior.

- Q: What do you need to run Crystal Space?

  A: You need the following items:

- Q: I downloaded Crystal Space but it won't run. What could be the cause?

  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.

  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.

  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 `‘components’` subdirectory. Most ports of Crystal Space use plug-in modules by default.

  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:

      % walktest flarge

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

  Alternately, for WalkTest, you can change the `‘WorldFile’` setting in its configuration file `‘CS/data/config-apps/walktest.cfg’`. For example:

      Walktest.Settings.WorldFile = flarge

  A5: If all else fails ask a question on the Crystal Space mailing list. See section Mailing Lists.

- Q: What documentation is available? Where can I find it?

  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. See Documentation Resources.

- Q: I'm using OpenGL with Crystal Space (via the `‘-video=opengl’` command-line option, for example) and the animation is extremely slow. What's wrong?

  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.

  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.

- 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?

  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.

  A2: The width and height of a texture must be a power of 2 (such as 8, 16, 32, 64, ...). 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!

  A3: Crystal Space textures may be in any of the supported image formats, such as PNG, TGA, BMP, JPG, MNG and GIF.

  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.

- Q: How can I actually make 3D models and maps for use in Crystal Space?

  A1: You can use Blender (http://www.blender3d.org/) together with blender2crystal (aka. b2cs, 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 `‘AniMesh’` models.

  A2: For animated models using Cal3D (see section SpriteCal3D Mesh Object) you can also use Blender, which has support for Cal3D objects. There is a tutorial on this subject at:

  http://www.cs.indiana.edu/~joellis/CSIntro.html

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

  http://www.crystalspace3d.org/docs/online/maxexporter/

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

  http://cal3d.sourceforge.net/modeling/tutorial.html

  A5: There is a tool to convert map files (from tools like Q3Radiant, Hammer, or QuArK) to CS. You can find this tool at:

  http://www-poleia.lip6.fr/~degris/converter/

  A6: There is a `‘Maya2Spr’` utility included with Crystal Space which can convert Maya files to 3D sprites. Not for maps, though.

  A7: There is a `‘3ds2lev’` utility to convert `‘.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.

  A8: There is `‘md22spr’` utility which can convert Quake MD2 and MDL models to Crystal Space 3D sprites. The animation frames are also properly converted. This will not generate Cal3D models!

  A9: There is md32spr utility which can convert Quake MD3 models.

- Q: I would like to contribute to Crystal Space. What can I do?

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

  http://sourceforge.net/projects/crystal/

  You can also contact the mailing list (see section Mailing Lists) in order to coordinate your efforts with those of other people.

- Q: How does Crystal Space work?

  A1 If you want to know how you can use CS, you can look at the See section Using Crystal Space. If you want to know how it works internally, See section Internal Project Structure.

  A2: Read any other documentation related to this project as mentioned earlier in this FAQ.

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

- Q: I want to write a game with Crystal Space. Can I do this?

  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.

  A2: Crystal Space is under the 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, Licenses.

- Q: How stable is the API for Crystal Space?

  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 `‘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.

The following section lists some more technical questions.

- Q: I have some objects but collision detection is not working on them. What is wrong?

  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 `HardTransform` or `<hardmove>` instead. Note that for some types of mesh objects (like 3D sprites) you must do this on the factory.

- Q: I have some objects that seem to be culled wrong. What can cause this?

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

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

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

  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.

- Q: Why can't I get the `iGeneralMeshState` / `iSprite3DState` / ... from my mesh wrapper? I do `scfQueryInterface` from the mesh and it returns `‘0’`.

  A: A common error is to try to query the state interface for a mesh object from the `iMeshWrapper` instance. However it is not `iMeshWrapper` that represents the mesh object. `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 `iMeshObject` instance instead. You can get this instance with `mesh->GetMeshObject()`.

- Q: I do not understand when I have to use `DecRef()` and when not. Can you explain this reference counting to me?

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

      csRef<iGeneralMeshState> st =
        scfQueryInterface<iGeneralMeshState> (mesh->GetMeshObject());
      if (st)
      {
        st->blabla ...;
      }

  You can use the `‘st’` variable just like you would use the normal `iGeneralMeshState` reference. The only difference with code that doesn't use smart pointers is that you don't have to take care of calling `DecRef`. See section Correctly Using Smart Pointers.

- Q: My objects are rendered incorrectly. It seems as if parts of it sometimes appear and sometimes disappear.

  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 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 `‘ZFILL’` mode for the room polygons (so that the Z-buffer will be filled but not read) and `‘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 `‘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 `‘ZUSE’` for all objects and enable Z-clearing every frame. In world files you can do this by using the `‘settings’` block and enabling the `‘clearzbuf’` option.

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

- Q: I'm trying to use some plugin but it says that it cannot find it (i.e. `csQueryRegistry` returns null).

  A: It is important to realize that `csQueryRegistry` does `‘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 `csInitializer::RequestPlugins()` and the second is to manually load the plugin using `csLoadPlugin`. `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).

- Q: How can I show FPS (Frames Per Second) in my Crystal Space application?

  A: Add the following entry to the user-specific application-neutral or application-specific domain (see section Configuration File):

      Global.System.Plugins.iBugPlug = crystalspace.utilities.bugplug

  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 FPS (among other things) and is otherwise not harmful. You can also use BugPlug to make screen-shots (press `Ctrl-d` followed by `F12`). See section Using the BugPlug Debugging Plugin.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated using texi2html 1.76.