| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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/tikiwiki/tiki-list_faqs.php
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/support/release/
You can also access the bleeding-edge developmental version. See section Where to Get 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.
A: You need the following items:
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.
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 `stdtex.zip' which contains all the textures.
Alternately, for WalkTest, you can change the `WorldFile' setting in its configuration file `CS/data/config/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.
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.
A1: You may want to decrease the size of the texture cache with the `-cache=<size>' command-line option or the `CACHE' configuration option in `soft3d.cfg' if you are using the software renderer. By default the size of the texture cache is quite large (typically 5 to eight megabytes in size), so adjusting this value might be useful for low-memory systems.
A2: Using a smaller window size and a lower bit-depth can also decrease memory usage. In addition to the memory used for the actual graphics display, Crystal Space uses a Z-buffer containing 4-byte values with the same dimensions as the display. Therefore, a display with dimensions of 640x480 uses a Z-buffer of 1,228,800 bytes.
A3: If you are still low on memory there is only one thing you can do: decrease the complexity of the map. For every polygon in the world a lot of memory used. If you just want to try the engine you can run Crystal Space with some of the simpler worlds such as `room.zip' or `maze.zip'.
A1: Crystal Space is a 6DOF engine. It needs to do semi-perspective correct texture mapping to get a nice display and calculations to achieve this are slow. You can expect that Crystal Space will probably need the same kind of computer as a game such as Quake 1 or Quake 2, at least a Pentium or a very fast 486 with a floating point co-processor. Also note that Crystal Space is still in the developmental stage and has not yet been fully optimized. You might try using smaller window dimensions with the `-mode=' option. See section Common Command Line Options.
A2: Use a hardware accelerated graphics card and driver. Such cards are quite popular these days and can perform extremely well, especially when compared to Crystal Space's software renderer. Framerates of 100 fps and more are not uncommon if you have a properly configured OpenGL renderer. Note that by default Crystal Space uses OpenGL. You have to use the `-video=software' command-line option to go back to Software rendering.
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.
A: Crystal Space is currently in the process of moving from the old renderer architecture to a new one. The new renderer supports advanced OpenGL features like shaders, stencil shadows, and a lot more but it is still in an experimental stage (although we feel it is already working rather well). Basically we recommend using the new renderer architecture unless it doesn't work for you (in which case we like to hear a report), you need the software renderer, or you require another feature of the new renderer that we don't support yet (like one of the missing meshes, fog, ...).
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 colors 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.
A1: For maps and objects using either `genmesh' or `thing' (i.e. non-animated) you can use Blender (http://www.blender3d.org/) together with Blend2CS (http://projects.blender.org/projects/blend2cs/). Blend2CS 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.
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 either `genmesh' or `thing' 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://lww.demon-host.com/html/guide/
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.
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.
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.
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.
A: The API which you can find in the 0.90 release should be about 95% stable as compared to the 1.0 release. After 1.0 we will make sure to keep backwards compatibility (until we release 2.0 :-)
The following section lists some more technical questions.
A: One of the most common errors is to scale an object using
the transform in the movable. Unfortunatelly 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.
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.
A: Both the software and OpenGL renderer have a limitation on lightmap size. For the software renderer the limitation is that the final resulting lit texture may not exceed 1500000 pixels. To calculate the final resulting lit texture size the easiest way is to take the texture size that is used on the polygon (i.e. 64x64 for example) and calculate how many times the texture is repeated on that polygon. If the given texture is repeated four times on the polygon then you basically have a total texture of 256x256 which will be fine. For the OpenGL renderer the limitation is that a lightmap cannot be bigger than 256x256. Note that there will be a lightmap lumel for every 16x16 texels on the polygon. To avoid this limitation you basically have five possible solutions: (1) split the polygon into smaller polygons, (2) use a smaller base texture (this will also reduce size of lightmap/lit texture), (3) decrease the number of times the texture is tiled on the polygon, (4) increase the size of the lumels (i.e. 32x32 instead of 16x16) by changing the `lightmapcellsize' option in the world file, and finally (5) use a low-resolution base texture and a high-resolution detail texture to add detail (this only works for OpenGL).
A: Crystal Space does not automatically recalculate lighting. To do that you have to use the `-relight' command-line option.
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.
iThingState / 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().
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<iThingState> st =
scfQueryInterface<iThingState> (mesh->GetMeshObject());
if (st)
{
st->blabla ...;
}
|
You can use the `st' variable just like you would use the normal
iThingState 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.
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()).
A1: Polygons in Crystal Space must be convex (meaning that every line between two random vertices of the polygon is fully contained in the polygon).
A2: The vertices of the polygon must all be on the same plane. For a triangle that is automatically the case.
A3: If you specify texture coordinates using `uv' on three of the polygon vertices then those three texture coordinates must be different.
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).
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 screenshots (press Ctrl-d followed by F12).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated using texi2html 1.76.