Raydium API Reference

Xfennec / CQFD Corp.

07/09/2002

1 Introduction

1.1 About

Well, first of all, let me talk about Raydium goals: this project aims to be simple, easy to use, portable, and quite fast.

Raydium is a C written abstract layer, on top of OpenGL, GLU and GLUT: this means you can write an entire 3D application without calling any OpenGL function. Want to draw an object ? call the suitable Raydium function, and all textures and vertices will be loaded, and your object drawn. Want to make an explosion ? Same thing: call the right function. Note that you can call OpenGL functions anyway, if necessary.

About portability, I can say a few things: Raydium was initially planned for linux only, but with an ``clean'' (nearly ANSI) code, and, in facts, we have been able to compile Raydium under VC6 (Windows ) with a very few modifications. So you can expect a correct result on any system providing OpenGL (at least 1.1), GLU, GLUT and a C compiler.

As we (CQFD Corp.) needed a library for our own games, demos, and... and things like that, and as I was interested by OpenGL, I starts to write Raydium.

Raydium is perfect for outdoors spaces, integrating a landscape engine, with suitable physic, supports dynamic lighting, fog, blending, water and waves, terraforming, and more.

This features list will probably grow up during Raydium developpement.

You'll find, in this document, an exhaustive list of all the functions and possibilities of Raydium.

After this short introduction, let's talk about the API itself, starting with the main file (from the programmer's point of vue) of Raydium: index.c

1.2 Defines

As mentioned above, the file index.c is quite interesting, for several reasons: first, as this file includes all others Raydium's files, you can have an overview of the whole project, just by looking at this.

It can also be used as a ``quick help'', since all variables are declared here, and not in the corresponding files. I mean, for example, that ``raydium_light_intensity[...]'' will be declared in index.c, not in light.c . There's many reasons for using such ``style'', but you must only retain that it is simpler for you :)

Ok, after this little disclaimer, we can have a look to the first part of our file.

After usual #include (nothing interesting here), we find some #defines.

1.2.1 generic limits

The first #define block determine limits of your application, and here you are the actual values:

#define RAYDIUM_MAX_VERTICES 500000

#define RAYDIUM_MAX_TEXTURES 256

#define RAYDIUM_MAX_LIGHTS 8

#define RAYDIUM_MAX_NAME_LEN 255

#define RAYDIUM_MAX_OBJECTS 1024

As you may expect, MAX_VERTICES defines the amount of memory you'll waste with vertex tables. These tables will contain all loaded objects, then remember each time you draw something (object), Raydium loads it (if not already done). Currently, there is no ``delete'' mechanism implemented (except by deleting all objects). Let me give you a scale: with an Athlon XP1900+, GeForce 3, actual Raydium devel. version 0.31, with around 100 000 vertices, losts of options (sky, blending, 2 lights, 15 textures, ...), Raydium renders 45 FPS. Beyond this, a very correct object uses less than 10 000 vertices. So 500 000 vertices, the actual default, is quite large. It's also important to talk about memory: Linux is very efficient on this point, and allocates only ``really used'' memory. Under Linux, with the above scene, Raydium used about 20 MB (data only), instead of ``much more'' ( 5x). I haven't made any test about this under Windows, but, we can expect worse results.
There's nothing really important about MAX_TEXTURES, since that doesn't influence the amount of memory used. You are not limited to 8 bits values, but 256 seems very comfortable (and you must pay attention to the capacities of your 3D hardware !)
The next define, MAX_LIGHTS is very important: OpenGL, for now (version 1.3 and lower), impose 8 lights at least, and all current hardware doesn't manage more. If this situation is likely to evolve, we will move this #define to a variable, and will ask hardware for its capacities at initialization, but, for the moment, do not exceed 8.
Next, NAME_LEN, limits the maximum length of strings (textures and objects names) used by Raydium. Default value should be perfect. (avoid higher values, since it could slow down name searches)
MAX_OBJECTS use the same mechanism as MAX_TEXTURES, and addition with the fact that hardware is not concerned, it can be ignored.

1.2.2 options and parameters

This is the next part of our #define section, I will not explain these constants here, but in respective sections, so you'll have just you to remember they're declared here.

1.3 vars quick view

This section aims to describe each variable Raydium use, one by one. Some (most ?) of them are used internaly only, but you could need to access it. Moreover, you'll better understand how Raydium works by looking at these variables.

1.3.1 keyboard input

Following variables can be found:

raydium_key_last will always contains the last key (normal or special) pressed down. You'll find a explanation about normal & special keys above.

raydium_key[] hosts all special keys state. Currently, you must use GLUT define's (Raydium aliases will come soon), limited to following keys:

GLUT_KEY_F1 to GLUT_KEY_F12
GLUT_KEY_LEFT, GLUT_KEY_RIGHT, GLUT_KEY_UP, GLUT_KEY_DOWN
GLUT_KEY_PAGE_UP, GLUT_KEY_PAGE_DOWN
GLUT_KEY_HOME, GLUT_KEY_END, GLUT_KEY_INSERT

These are ``special'' keys: they have 2 states. released (0), and pressed (non zero). It means you can do something (move an object, turn on a light) UNTIL user stops to press the key. ``Normal'' keys have a different behavior: you can do something IF user press a key (exit from application if ESC is pressed, for example). You'll have no information about key's release.

A normal key is sent through raydium_key_last, a special one through raydium_key[] AND raydium_key_last.

You must see raydium_key_last as an ``event'', fired when the user press a key (ANY key: special or not). When a normal key is pressed, you'll get the ASCII value + 1000 assigned to raydium_key_last. (1027 for ``ESC'', for example)

Here is a method to use special keys: if(raydium_key[GLUT_KEY_UP]) move_car();

Yes, it's easy. You can also use if(raydium_key_last==GLUT_KEY_UP) explose(); for example, if you need to carry out a specific action.

It's ok for you ? use raydium_key[] to keep the car moving until user release UP key, or use raydium_key_last to explode the car when the user tries to start it :)

1.3.2 mouse input

Easy.

You can get actual mouse position on the window (relative to window's position on screen, I mean) with raydium_mouse_x and raydium_mouse_y (GLuint), starting at (0,0) for upper left (Warning: some GLUT implementation can give mouse position even when mouse is out of the window ! Check boundaries before using these values).

Raydium use: 1 for left button, 2 for right button, and 3 for middle button (0 for none) with raydium_mouse_clic for the last clic value. (generated one time per clic)

You can permanently get a button's state, up (0) or down (non zero), using raydium_mouse_button[x], where x is 0 for left button, 1 for right one, and 2 for middle button.

1.3.3 textures

raydium_texture_index and raydium_texture_current (GLuint) are used internaly to determine repectively how many textures are loaded, wich is the current one.

The next variable, raydium_texture_filter, is very important. You can assign RAYDIUM_TEXTURE_FILTER_NONE (default), RAYDIUM_TEXTURE_FILTER_BILINEAR or RAYDIUM_TEXTURE_FILTER_TRILINEAR (recommended).

Using no texture filter can gives you higher framerate on old 3D hardware, but quite ugly.

You can activate bilinear filtering without any framerate impact on most recent video cards, and get a much more attractive rendering.

Trilinear filtering uses Bilinear filtering and MIPMAPs. A MIPMAPed texture is a duplicated texture (3 times, with Raydium), but at different sizes. A 512x512 texture will generate, for example, a (smoothed) 256x256 texture, and a (smoothed) 128x128 one. Your video card will use these textures according to distance from POV (point of vue), reducing flickering effect.

This is the best filtering Raydium can use, for a great rendering quality. Goog and recent 3D hardware can do trilinear filtering in a single pass, so it must be the default setting for your application.

About raydium_texture_filter itself: changing this variable will not modify the rendering, but the way to load textures. It means you can (for example) use trilinear only for landscape textures, and bilinear for others. It also means you must reload (erase) a texture to change it's filter.

Note that Raydium will never use trilinear filter with blended (transparent) textures, for good reasons :)

Let's talk quickly about next (internal) texture variables: raydium_texture_blended[] is a flag table, where each element is non zero for a blended (RGBA) texture, and 0 for an RGB one.

For Raydium, when a texture does not contain a ``bitmap'' (texture file, for example), it contains a plain color, and this color is stored in raydium_texture_rgb[][4] (4 is for RGBA, values between 0 and 1). You can load an rgb texture with ``rgb'' keyword. For example, instead of loading ``red.tga'', you can load ``rgb(0.8,0.1,0.1)''.

raydium_texture_name[] table simply contains texture filenames.

Last thing, raydium_texture_to_replace, can be used to erase an already loaded texture. Set the variable to n, and load a new texture: texture number ``n'' will be replaced in memory.

1.3.4 projection

Raydium supports 2 types of projection: RAYDIUM_PROJECTION_ORTHO (orthographic) and RAYDIUM_PROJECTION_PERSPECTIVE.

First of all, let us point out what ``projection'' is. Using a ``perspective'' projection, closest objects will looks larger than the orthers. It is typically used in video games (since human eye runs like that), by opposition to orthographic projection, wich is mostly used by 3D modeling tools. The principle is simple, discover it by yourself :)

Raydium reads raydium_projection to determine wich method to use. Each projection is configured with raydium_projection_* variables. Some of these variables are used both by ``perspective'' and ``orthographic'' projections.

Here is what index.c says:

GLFLOAT RAYDIUM_PROJECTION_FOV; // PERSPECTIVE ONLY

GLFLOAT RAYDIUM_PROJECTION_NEAR; // PERSPECTIVE & ORTHO

GLFLOAT RAYDIUM_PROJECTION_FAR; // PERSPECTIVE & ORTHO

GLFLOAT RAYDIUM_PROJECTION_LEFT; // ORTHO ONLY

GLFLOAT RAYDIUM_PROJECTION_RIGHT; // ORTHO ONLY

GLFLOAT RAYDIUM_PROJECTION_BOTTOM; // ORTHO ONLY

GLFLOAT RAYDIUM_PROJECTION_TOP; // ORTHO ONLY

You probably noticed that orthographic projection defines a ``box'' with your screen: near, far, left, right, bottom. Everything out ouf this box will never be displayed.

Perspective projection is based on FOV: Field Of Vision, given in degrees. A common ``human'' fov is 60^, up to 90^ without any noticeable deformation. ``near'' and ``far'' are used for many things: Z-Buffer precision is affected, and clipping too: as with ``orthographic'', nothing will be displayed beyond ``far'', and fog, if enabled, will hide this ``limit''. This is right for ``near'', too, but without fog, obviously :)

Also remember that decreasing FOV will zoom in.

You must call raydium_window_view_update() after any modification on one (or more) of these variables (see ``Window Managment'' section for more information)

1.3.5 frame size and color

raydium_window_tx and raydium_window_ty are read-only variables, providing you actual frame size.

raydium_background_color[4] is an RGBA table, and will be used for frame clearing, and fog color. You can change this variable, and call respective update functions (frame and fog), or simply use raydium_background_color_change(GLfloat r, GLfloat g, GLfloat b, GLfloat a).

More informations in corresponding sections.

1.3.6 vertices

Vertices data structure is distributed in 4 parts:

*raydium_vertex_* : these tables will simply contains vertices coordinates
*raydium_vertex_normal_* : vertices normals. Raydium will maintain two distinct normal tables, and this one will be used for calculations.
*raydium_vertex_normal_visu_* : the other normal table, used for lighting. Smoothing ``visu'' normals will provides a better rendering, and Raydium includes all necessary functions to automate this task.
*raydium_vertex_texture_u, *raydium_vertex_texture_v, *raydium_vertex_texture contains, for each vertex stored in the vertices data structure, u and v mapping information, and associated texture number. U and V are texture mapping coordinates.

Raydium can automatically generates some of these data (normals and uv coords, that is), Read ``Vertices'' section above for more information.

PLEASE, do not write directly in these tables, use dedicated functions.

1.3.7 objects

Objects are loaded in vertices stream, identified by a ``start'' and an ``end'' (raydium_object_start[] and raydium_object_end[]) in this stream. An index is incremented each time you load an object (GLuint raydium_object_index). Filename is also stored in raydium_object_name[][]. Go to ``Objects'' section to know more.

1.3.8 lights

First of all, raydium_light_enabled_tag contains 0 when light is disabled, non-zero otherwise. This is a read-only variable, so use suitable functions.

Currently, for Raydium, a light can have 3 states: on, off, or blinking.raydium_light_internal_state[] stores this.

Next comes all light's features: position, color, intensity. You can modify directly these variables, and call update fonctions, if needed (not recommended).

Next, raydium_light_blink_* are used internaly for blinking lights, setting lowest, higher light intensity, and blinking speed. Do noy modify these variables, use suitable functions.

1.3.9 fog

Only one variable, here: raydium_fog_enabled_tag, switching from zero to non zero if fog is enabled. Do NOT use this variable to enable or disable fog, but suitable functions, this variable is just a tag.

1.3.10 camera

Since many calls to camera functions are done during one frame, Raydium must track if any call to these functions was already done, using raydium_frame_first_camera_pass boolean.

raydium_camera_pushed, also used as a boolean, stores stack state. When you place your camera in the scene with Raydium, it pushes matrix on top of the stack, so you can modify it (the matrix), placing an object for example, an restore it quickly after, by popping matrix off.