Raydium API Reference

CQFD Corp.

This document is the most up-to-date version. This is a work in progress:
there's again some errors and wrong informations. Try, wait, or contribute ;)

Index of chapters
Index of all Raydium functions

---

This document is autogenerated, any change will be lost,
use RaydiumApiReferenceComments for any need.
Generated: 2008-08-20 00:42:30, for Raydium 0.800

---

1 Introduction to Raydium:

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,
and GLU: 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 a "clean" (nearly ANSI) code,
and, in facts, we have been able to compile Raydium under Visual Studio (Windows)
and mingw with a very few modifications.
So you can expect a correct result on any system providing
OpenGL (at least 1.2), GLU and a C compiler. Using Raydium as a shared
library (.so or DLL), you can also use C++ language for you own applications

As we (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, reflections, and more, but also provides everything for indoor,
with radiosity lightmaps for example.

Some other advanced features are available : physics, scripting,
live video, transparent networking, GUI, shaders, ...

This features list will probably grow up during Raydium developpement, see
Raydium website: http://raydium.org/

You'll find, in this document, a list of many functions and possibilities
of Raydium, but if it's your first view of Raydium, you should
start with tutorials ( http://wiki.raydium.org/wiki/RaydiumTutorials ) and
packaged demo programs.

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: common.c

1.2 Defines:

As mentioned above, the file common.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 common.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.

generic limits

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


- 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 to say 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.

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 Basic vars:

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.

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 and 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:


Yes, it's easy. You can also use

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 :)

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 implementations 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_click for the last click
value. (generated one time per click)
Raydium will now use 4 (up) and 5 (down) for mouse wheel, if any.

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.

Textures

raydium_texture_index and raydium_texture_current_main (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).
Raydium now support anisotropic filtering with RAYDIUM_TEXTURE_FILTER_ANISO.
Do not change the variable yourself, use the raydium_texture_filter_change()
function instead, it allows the user to override your setting from the
command line (--filer option).

Using no texture filter can gives you higher framerate on old 3D hardware,
but this is 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.
Good 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.

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 common.c says:



You've 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)

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 a 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.

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.

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.

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.

You should read the chapter dedicated to lights for more information.

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.

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.

2 Maths:

2.1 Little introduction to trigo.c:

This section is mostly designed for internal uses, but provides some
usefull maths functions, mostly for trigonometrical uses.

2.2 GLfloat raydium_trigo_cos (GLfloat i):

Obvious (degrees)

2.3 GLfloat raydium_trigo_sin (GLfloat i):

Obvious (degrees)

2.4 GLfloat raydium_trigo_cos_inv (GLfloat i):

Obvious (degrees)

2.5 GLfloat raydium_trigo_sin_inv (GLfloat i):

Obvious (degrees)

2.6 raydium_trigo_abs(a) (macro):

Obvious

2.7 raydium_trigo_min(a,b) (macro):

Obvious

2.8 raydium_trigo_max(a,b) (macro):

Obvious

2.9 raydium_trigo_isfloat(a) (macro):

Test two cases : "Not a Number" and "Infinite"

2.10 raydium_trigo_round(a) (macro):

Will obviously "round" a instead of the default C floor behaviour

2.11 void raydium_trigo_rotate (GLfloat * p, GLfloat rx, GLfloat ry, GLfloat rz, GLfloat * res):

Rotate p (GLfloat * 3) by (rx,ry,rx) angles (degrees).
Result is stored in res (GLfloat * 3)

2.12 void raydium_trigo_pos_to_matrix (GLfloat * pos, GLfloat * m):

Generates a ODE style matrix (16 Glfloat) from pos (GLfloat * 3)

2.13 void raydium_trigo_pos_get_modelview (GLfloat * res):

Stores the translation part of the current OpenGL MODELVIEW matrix in res (3 GLfloat)

2.14 int raydium_trigo_pow2_next(int value):

Returns next power of two of value. Ugly.

2.15 Matrix functions:

Here there are a few functions also designed for internal uses that aims
only at matrices. Really the main objective of these functions is give support
for the inverse function.
The data type matrix4x4 is really an 16 double array.

2.16 double raydium_matrix_determinant(matrix4x4 matrix):

Returns the determinant of the given matrix.

2.17 matrix4x4 raydium_matrix_adjoint(matrix4x4 matrix):

Returns the adjoint matrix of the given matrix.

2.18 matrix4x4 raydium_matrix_multiply(matrix4x4 matrix1, matrix4x4 matrix2):

Returns the resulting matrix of the multiplication of 2 matrices.
Remeber that the multiplication of matrices doesn't have the conmutative
property, so is not equal matrix1 X matrix2 than matrix2 x matrix1.

2.19 matrix4x4 raydium_matrix_inverse(matrix4x4 matrix):

Returns the inverse matrix of a given matrix.

2.20 double raydium_matrix_internal_determinant(matrix4x4 matrix, int dimension):

internal, don't use.

2.21 matrix4x4 raydium_matrix_internal_adjoint(matrix4x4 matrix, int dimension):

internal, don't use.

2.22 matrix4x4 raydium_matrix_internal_multiply(matrix4x4 matrix_one, matrix4x4 matrix_two, int dimension):

internal, don't use.

2.23 matrix4x4 raydium_matrix_internal_inverse(matrix4x4 adjoint_matrix,double det,int dimension):

internal, don't use.

2.24 int _raydium_trigo_MatrixInverse(const float *m,float *out):

Our matrix_inverse seems broken.
This code works, thanks to Alexander Zaprjagaev (frustum@public.tsu.ru)
This code is not native

2.25 void raydium_trigo_quaternion_normalize(float *quat):

Normalize quat quaternion. I suppose such code is already available
in ODE.

2.26 void raydium_trigo_quaternion_slerp(float *start, float *end, float alpha,float *result):

Spherical Linear Interpolation of quaternions, from start to end
with alpha [0,1] as interpolation point.

3 Logging:

3.1 Introduction to log.c:

Raydium uses and provides his own logging system,
hidden behind a single function, as shown below.

3.2 void raydium_log (char *format, ...):

This function must be used like "printf", using a format
("%s, %i, %x, ...") and then, suitable variables,
but without the end-line char ('\n')



For now, this function writes to the parent terminal and the in-game console, with "Raydium: " string prefix.
The user can force logging to a file, using --logfile command line switch.

4 Random:

4.1 Introduction:

These functions deals with random numbers generation.

4.2 void raydium_random_randomize (void):

This function initialize the random number generator
with current time for seed.
Note: You are not supposed to use this function.

4.3 GLfloat raydium_random_pos_1 (void):

"positive, to one": 0 <= res <= 1

4.4 GLfloat raydium_random_neg_pos_1 (void):

"negative and positive, one as absolute limit": -1 <= res <= 1

4.5 GLfloat raydium_random_0_x (GLfloat i):

"zero to x": 0 <= res <= x

4.6 GLfloat raydium_random_f (GLfloat min, GLfloat max):

min <= res <= max (float)

4.7 int raydium_random_i (int min, int max):

min <= res <= max (integer)

4.8 signed char raydium_random_proba (GLfloat proba):

Returns true or false (0 or 1) depending of "proba" factor.
proba must be: 0 <= proba <=1
ex: 90% = 0.9 (this will "very probably" return true)

5 Fog:

5.1 Introduction:

Fog is usefull for two major reasons:

1. Realism: Just try, and you'll understand:
amazing depth impression, no ?

2. Speed: For a correct fog effect (i'm talking
about estetic aspect), you must bring near_clipping to a closer value,
reducing the overall number of triangles displayed at the same time.

There are 3 types of fog. They are:
* Linear: fog = (Far-z) / (Far-Near)
* Exp: fog = e^(-density*z)
* Exp2?: fog = e^((-density*z)^2)

Above z is the distance to the calculated point from the camera.
As you can see, linear mode doesn't use density, and Exp & Exp2? modes don't
use near and far values. Remember that.

5.2 void raydium_fog_enable (void):

Obvious

5.3 void raydium_fog_disable (void):

Obvious

5.4 void raydium_fog_color_update (void):

If you have modified raydium_background_color array, you must
call this function, applying the specified color to hardware.
See also: raydium_background_color_change

5.5 void raydium_fog_mode(GLuint mode):

The fog mode can be change with this function. There are 3 different ways
to apply the fog:

1. RAYDIUM_FOG_MODE_LINEAR - Used by default, the fog is directly applied
according the distance. Not real world fog, but used to avoid drawing
too distant objects.
IMPORTANT: EXP mode ignores the density value,
only uses near and far.

2. RAYDIUM_FOG_MODE_EXP - The fog grows exponentially with the distance.
Usual mist in the real world.
IMPORTANT: EXP mode ignores the near and far values,
only uses the density.

3. RAYDIUM_FOG_MODE_EXP2 - The fog grows twice exponentially with the
distance. Used when the observer is inside a cloud/mist.
IMPORTANT: EXP2 mode ignores the near and far values,
only uses the density.

5.6 void raydium_fog_density(GLfloat density):

Sets the density of the fog.
Useless if you are using LINEAR mode.

5.7 void raydium_fog_near(GLfloat near):

Sets the near point to apply the fog.
Useless if you are using EXP or EXP2 modes.

5.8 void raydium_fog_far(GLfloat far):

Sets the far point of the fog.
Useless if you are using EXP or EXP2 modes.

5.9 void raydium_fog_apply(void):

Used to apply changes in your setup of fog.
Also is used to continue a previously stopped fog.
See: raydium_fog_wait() below.

5.10 void raydium_fog_wait(void):

With this function you can deactivate TEMPORALY the fog, but the internal state
of the fog in Raydium won't change, so when you use raydium_fog_apply, the fog
will continue like it was before being stoped.
It's very usefull for certain rendering effects that need to
stop the fog temporaly.

5.11 void raydium_fog_volumetric_support(void):

With this function, you're saying to Raydium that you want a support
for volumetric fog in you application. Call this function as soon as possible
after engine init, since it will change the way Raydium renders objects (think
about display lists).

5.12 void raydium_fog_volumetric_enable(void):

When you call this function, fog is no more applied using fragment depth,
but using RENDER_VOLUMETRIC_FOG_AXIS (see config.h).
You must have called raydium_fog_volumetric_support() before enabling
volumetric fog.

5.13 void raydium_fog_volumetric_disable(void):

Reset fog sytem to default behavior (fragment depth).

6 Window management:

6.1 Introduction:

Some important functions, used for window creation and managment.

6.2 void raydium_window_close (void):

This function is called by Raydium, do not use.

6.3 void raydium_window_create (GLuint tx, GLuint ty, signed char rendering, char *name):

You must call this function once in your program, with following arguments:

1. tx, ty: window size, in pixel
2. rendering: window mode: RAYDIUM_RENDERING_* (NONE, WINDOW, FULLSCREEN)
3. name: window's name

Raydium is using GLUT for window management, and GLUT fullscreen is not
the same between various implementations, and can fail,
so use a standard window size (640x480, 800x600, ...) for fullscreen mode.

Note that user can force fullscreen using --fullscreen on the command line.

6.4 void raydium_window_resize_callback (GLsizei Width, GLsizei Height):

This function is automaticaly called during a window resize,
and resize OpenGL rendering space.

There is almost no reason to call this function by yourself.

6.5 void raydium_window_view_update (void):

If you've changed 3D window size (clipping: raydium_projection_*),
apply to hardware with this fonction.

6.6 void raydium_window_view_perspective(GLfloat fov, GLfloat fnear, GLfloat ffar):

All-in-one function: sets all "perspective" variables, and updates.

7 Capture (2D):

7.1 Quickview:

Captures are made in TGA (without RLE compression) or JPEG formats and saved into
the current directory.
These functions may fail (garbage in resulting capture) if frame size if
not "standard", mostly after a window resize.

Also there are "auto" functions that provide a simplest method to make an screen
capture. So,the following example (put into the display() function), allows jpeg
screenshots just pressing F9 key:


Raydium also allow you to capture movies: activate DEBUG_MOVIE option
in raydium/config.h with the needed framerate, and press F11. Raydium
will use a dedicated time line, allowing smooth capture. This system may cause
strange behaviours with movies providing network action.
The movie is stored in multiples files in movie directory, and you can
use mencoder like this:
mencoder -ovc lavc -lavcopts vcodec=mpeg4:vhq:vbitrate=780
mf://\*.tga -vf scale=320:240 -mf fps=25 -o ~/ray.avi
You can also use audio file adding this:
-audiofile audio.mp3 -oac copy for example.

7.2 void raydium_capture_frame(char *filename):

Capture current frame to filename.

7.3 void raydium_capture_frame_auto(void):

Same as above, but to an auto-generated filename (raycap*).

7.4 void raydium_capture_frame_jpeg(char *filename):

Same as raydium_capture_frame() but using JPEG image format.
See raydium/config.h for quality setting.

7.5 void raydium_capture_frame_now(char *filename):

Same as raydium_capture_frame(), but without waiting the end of the frame,
saving the hardware color buffer, whatever it contains. Use with caution.

7.6 void raydium_capture_frame_jpeg_now(char *filename):

Same as above, but using JPEG image format.

7.7 void raydium_capture_filename_auto(char *dest,char *format):

Internal Use. Generates filenames for new screenshots.

7.8 void raydium_capture_frame_auto(void):

Capture the current frame giving the resulting file and automatic name.

7.9 void raydium_capture_frame_jpeg_auto(void):

Same as above, but using JPEG image format.

8 Background:

8.1 void raydium_background_color_change (GLfloat r, GLfloat g, GLfloat b, GLfloat a):

Will change raydium_background_color array and apply this modification.
(will update fog color, obviously).

9 Frame clearing:

9.1 void raydium_clear_frame (void):

You need to call this function every frame to clear all hardware buffers.

9.2 void raydium_clear_color_update (void):

Will apply background color modification. Probably useless for you.

10 Lights:

10.1 Introduction to Raydium light system:

When we starts Raydium development, the main idea was to use native OpenGL
lights, and not lightmaps or another method.

This method (native lights) provides 8 simultaneous movable lights,
and is quite effective with recent OpenGL hardware.

You can modify intensity, position, color, you can turn on any light at
any time, make them blinking... Mixing all theses features can result
many effects, as realtime sunset, flashing lights for cars, explosions, ...

Usage is very easy: no need to create lights, just turn them on.

See also: LightMaps

10.2 void raydium_light_enable (void):

Obvious.

10.3 void raydium_light_disable (void):

Obvious.

10.4 signed char raydium_light_texture(int texture, signed char enable):

Texture l will not use lighting if enable is set to 0. Call this
function before loading any object using this texture, because
of display lists. Same way, it's not possible to change back this value
after the first object drawing without disabling display lists.

10.5 signed char raydium_light_texture_name(char *name, signed char enable):

Same as above, but using texture name.

10.6 GLuint raydium_light_to_GL_light (GLuint l):

Probably useless for end user. (internal uses)

10.7 void raydium_light_on (GLuint l):

Turns l light on ( 0 <= l <= RAYDIUM_MAX_LIGHTS )

10.8 void raydium_light_off (GLuint l):

Turns l light off

10.9 void raydium_light_switch (GLuint l):

Will swith l light state (from "on" to "off", for example).

10.10 void raydium_light_update_position (GLuint l):

Updates raydium_light_position[l] array changes to hardware.
This function is now used internaly by Raydium,
so you have no reasons to call it by yourself.

10.11 void raydium_light_update_position_all (void):

See above.

10.12 void raydium_light_update_intensity (GLuint l):

See above.

10.13 void raydium_light_update_all (GLuint l):

See above.

10.14 void raydium_light_move (GLuint l, GLfloat * vect):

Moves light to position vect for light l (vect is GLfloat[4]: x,y,z,dummy).

Just move your lights before camera placement, or your changes
will be applied to the next frame only.

10.15 void raydium_light_reset (GLuint l):

This function will restore all defaults for l light.

10.16 void raydium_light_blink_internal_update (GLuint l):

Useless for end-user.

10.17 void raydium_light_blink_start (GLuint l, int fpc):

Makes l light blinking at fpc (frames per cycle) rate.
This function will use timecalls soon ("fpc" -> "hertz")

10.18 void raydium_light_callback (void):

Useless for end-user.

11 Keyboard & keys:

11.1 void raydium_key_normal_callback (GLuint key, int x, int y):

Internal callback.

11.2 void raydium_key_special_callback (GLuint key, int x, int y):

Internal callback.

11.3 void raydium_key_special_up_callback (GLuint key, int x, int y):

Internal callback.

11.4 int raydium_key_pressed (GLuint key):

Will return state of key in the raydium_keys[] array.
This function is usefull to test keyboard from PHP, since RayPHP doest not
support array for now.

12 Mouse:

12.1 Introduction:

Mouse API is almost explainded at the top of this guide, but here it
is some other usefull functions (macros, in facts)

12.2 raydium_mouse_hide() (macro):

Hides mouse cursor.

12.3 raydium_mouse_show() (macro):

Shows mouse cursor.

12.4 void raydium_mouse_move(int x, int y):

Moves cursor to (x,y) position (in pixel).
Example if you want to move cursor at window's center:

12.5 signed char raydium_mouse_isvisible(void):

Returns true or false (0 or 1), if the mouse is visible or not.
See raydium_mouse_show() and raydium_mouse_hide() above.

12.6 void raydium_mouse_init (void):

Internal use.

12.7 void raydium_mouse_click_callback (int but, int state, int x, int y):

Internal callback.

12.8 void raydium_mouse_move_callback (int x, int y):

Internal callback.

12.9 int raydium_mouse_button_pressed (int button):

returns button state. (See first part of this document)

13 Textures:

13.1 Introduction:

For now, Raydium only handles TGA uncompressed texture.
As explainded in the first part of this guide, Raydium provides three
texture filters (none, bilinear, trilinear using MipMaps ).

Texture sizes must be a power of two, 8 (alpha mask), 24 (RGB) or 32 (RGBA) bits.

Raydium supports simple color materials, using a "rgb(r,g,b)" string
as texture name, where r, g and b are 0 <= x <= 1 (floats).
With 3 negative values, you will generate a "phantom texture". Phantom textures
are only drawn into the z-buffer (and not color buffer).
Texture clamping and advanced multitexturing effects are supported by Raydium,
but not documented here for now. If you're interested, have a look at source
code, or take a look at the Wiki. Tips: "BOX", "ENV", "HDR", ";", "|".

Effective environment mapping (one pass, two texture units) is available using
a special filename separator for texture field in TRI files : #
See this example:
0.232258 0.225387 -0.149804 0.012198 -0.274925 0.961388 0.731411 0.980236 fiesta_diffuse.tga#ENV_map.tga
Environment texture name must start with "ENV" to allow spherical mapping, wich
is needed for such effect. See also RAYDIUM_RENDER_REFLECTION_FACT in
file common.h if you want reflection to be more or less visible.

This separator can also be used for shaders, to load multiple textures in the
hardware (up to RAYDIUM_RENDER_MAX_TEXUNITS on the same line of the tri file).

13.2 signed char raydium_texture_size_is_correct (GLuint size):

Returns true if size is a correct texture size, depending of
hardware capacities and "power of 2" constraint.

13.3 GLuint raydium_texture_load_internal(char *filename, char *as, signed char faked, int faked_tx, int faked_ty, int faked_bpp, int or_live_id_fake):

Internal use.

13.4 GLuint raydium_texture_load (char *filename):

Loads "filename" texture into hardware memory. Function results
texture index, but in most cases, you can identify later a texture
by his name, without providing his index, so you can probably ignore
this value.

0 is returned if texture loading have failed.

13.5 GLuint raydium_texture_load_erase (char *filename, GLuint to_replace):

Same as above, but to_replace texture (index) is erased with filename.

13.6 void raydium_texture_free(int number):

experimental function to free textures

13.7 void raydium_texture_free_name(char *name):

experimental function to free textures by its name

13.8 int raydium_texture_is_slot_used(int slot):

Returns true (1) if the texture slot is used for a texture, and
therefore, valid.

13.9 int raydium_texture_get_next_free_slot_internal(void):

Internal use. Will search a new free texture slot.

13.10 signed char raydium_texture_current_set (GLuint current):

Switch active texture to "current" index. Mostly used for runtime object
creation:
"set current texture, add vertices, set another texture,
add vertices, ... and save all to an objet"
(see below for vertices management).

13.11 signed char raydium_texture_current_set_name (char *name):

Same as above, but using texture name. This function will load name
if not alread done.

13.12 GLuint raydium_texture_find_by_name (char *name):

Returns index for texture "name", and load it if not already done.

13.13 GLint raydium_texture_exists(char *name):

Same as above, but don't load texture if name isn't already loaded and
then returns -1. Returns texture id otherwise.

13.14 void raydium_texture_npot_enable(void):

You can allow the load of Non-power-of-two textures with this function.

13.15 void raydium_texture_npot_disable(void):

Function to disabled the previous behaviour. By default Raydium already
has this behaviour disabled.

13.16 void raydium_texture_filter_change (GLuint filter):

Change texture filter. The new filter will apply on all "next" textures,
but will not change already loaded ones (this was the case in old Raydium
releases), since it may generate strange bugs with dynamic (aka "faked")
textures, and it was very slow.

13.17 void raydium_texture_compression(signed char enable):

This function allows Raydium to compress textures if hardware supports this
feature. You can also use the "--compress" command line switch.
The default is 0 ("no").

14 Rendering:

14.1 Introduction:

render.c contains Raydium rendering core, so only "public" and
interesting function will be documented.

A few variable may be very useful here. First, you can see how many frames
were rendered during last second, reading raydium_render_fps (interger,
read only). This variable is refreshed every second. If you need a
instantaneous measure, see below.

You may also read raydium_frame_time (float, read only) since it gives you
the elasped time during the last frame ! (in seconds). This a very easy way
to make framerate independent things. See this example, featuring two different
uses of this variable:


Note that you can have instantaneous framerate with, for instance:


As a note, I must said that it' obvious for me that many parts of render.c
have to be rewritten (tips: slow, buggy, old, ... :)

14.2 void raydium_render_lightmap_color(GLfloat *color):

You may force a new lightmap rendering color "filter" anytime with this
function, allowing advanced lighting effects.
HUGE WARNING: You must turn off display lists if you change this value after
first object's render.
See raydium_rendering_displaylists_disable() if needed.

14.3 void raydium_render_lightmap_color_4f(GLfloat r, GLfloat g, GLfloat b, GLfloat a):

Same as above, using 4 values.

14.4 int raydium_rendering_prepare_texture_unit (GLenum tu, GLuint tex):

This function will "prepare" hardawre texture unit tu to render tex texture.
There almost no reason to call this function by yourself.

14.5 void raydium_rendering_internal_prepare_texture_render (GLuint tex):

Same as above, but for texture unit #0 only.

14.6 void raydium_rendering_internal_restore_render_state (void):

Internal. Deprecated.

14.7 void raydium_rendering_from_to_simple(GLuint from, GLuint to):

Same as raydium_rendering_from_to(), but only with vertices (no
UV, no normals, no textures, no colors, ...).
Mostly used for internal shadow maps creation.

14.8 void raydium_rendering_from_to (GLuint from, GLuint to):

Renders vertices from from to to.
Using object management functions is a better idea.

14.9 void raydium_rendering (void):

Renders all vertices (probably useless, now).

14.10 void raydium_rendering_finish (void):

You must call this function at the end of each frame. This will flush all
commands to hardware, fire a lot off callbacks, and prepare next frame.

14.11 void raydium_rendering_wireframe (void):

Switch to wireframe rendering.

14.12 void raydium_rendering_normal (void):

Switch back to standard rendering.

14.13 void raydium_rendering_rgb_force (GLfloat r, GLfloat g, GLfloat b):

Force all RGB colored vertices to take (r,g,b) color. One example of this
use is for making "team colored" cars : Do not apply textures to some faces
while modelling, and force to team color each time you render a car.

14.14 void raydium_rendering_rgb_normal (void):

Disable "rgb force" state. See above.

14.15 void raydium_rendering_displaylists_disable(void):

Disable display lists usage.
Some old video cards and broken drivers may get better performances WITHOUT
display lists (on large objects, mainly).

14.16 void raydium_rendering_displaylists_enable(void):

Enable display lists usage. default state.

14.17 void raydium_render_fps_limit(float maxfps):

This function changes the maximum number of frames per second.
Sometimes is wanted to reduce the consumption of cpu cycles by our application.
In this situations we can use a method for delay each frame of the game
until a desired framerate. In that way the residual frames won't be processed
and a "lot" of cpu cycles will be saved.
Also can be used to increase the stability in certains systems.
Set maxfps to 0 if you want to disable this limit (this is the default).

15 Particle engine:

15.1 Introduction:

This is the second version of Raydium's particle engine. This engine is build
on top of a dedicated file format (.prt and .sprt files), describing most
(up to all, in facts) properties of generators.
It probably better to start by an example (fountain.prt) :


.prt files are readed using parsing functions (see appropriate chapter, if
needed), and the list of all available properties can be found in particle2.c
source file. A full toturial is also available on Raydium's Wiki.

Once the particle file is written, you only need to load the file using the
suitable function (see below). Some anchor are available to link generators to
physic entities, if needed, as callbacks for a few events (one, for now).

.sprt files are used to create a "snapshot" of particles, used for example by
3D captures, and are not meant to be edited by hand.

15.2 void raydium_particle_name_auto (char *prefix, char *dest):

Will generate a unique string using prefix. The string is created using
space provided by dest.
You can use this function when building a new generator.

15.3 void raydium_particle_init (void):

Internal use.

15.4 signed char raydium_particle_generator_isvalid (int g):

Internal use, but you can call this function if you want to verify if a
generator's id is valid (in bounds, and loaded).

15.5 int raydium_particle_generator_find (char *name):

Lookups a generator using is name. Returns -1 if name is not found.

15.6 int raydium_particle_find_free (void):

Finds a free particle slot.

15.7 void raydium_particle_generator_delete (int gen):

Deletes a generator.

15.8 void raydium_particle_generator_delete_name (char *gen):

Same as above, but using generator's name.

15.9 void raydium_particle_generator_enable (int gen, signed char enabled):

Activate a disabled generator (see below).

15.10 void raydium_particle_generator_enable_name (char *gen, signed char enable):

Disable a generator (TTL is still decremented).

15.11 void raydium_particle_preload (char *filename):

Loads .prt file and associated textures into suitable caches.
Call this function if you want to avoid (small) jerks caused by "live"
loading a generator.

15.12 void raydium_particle_generator_load_internal (int generator, FILE * fp, char *filename):

Internal use.

15.13 int raydium_particle_generator_load (char *filename, char *name):

Loads generator from filename as name. This name will be used for
future references to this generator, as the returned interger id.

15.14 void raydium_particle_generator_update (int g, GLfloat step):

Internal use.

15.15 void raydium_particle_update (int part, GLfloat step):

Internal use.

15.16 void raydium_particle_callback (void):

Internal use.

15.17 int raydium_particle_state_dump(char *filename):

Dumped current particles to filename (.sprt [static particles]).

15.18 int raydium_particle_state_restore(char *filename):

Append .sprt filename to current scene.

15.19 void raydium_particle_draw (raydium_particle_Particle * p, GLfloat ux, GLfloat uy, GLfloat uz, GLfloat rx, GLfloat ry, GLfloat rz):

Internal use.

15.20 void raydium_particle_draw_all (void):

Internal use.

15.21 void raydium_particle_generator_move (int gen, GLfloat * pos):

Moves gen generator to pos position (3 * GLfloat array).

15.22 void raydium_particle_generator_move_name (char *gen, GLfloat * pos):

Same as above, but using generator's name.

15.23 void raydium_particle_generator_move_name_3f (char *gen, GLfloat x, GLfloat y, GLfloat z):

Same as above, using 3 different GLfloat values.

15.24 void raydium_particle_generator_particles_OnDelete (int gen, void *OnDelete?):

Sets a callback for gen, fired when any particle of this generator is
deleted, providing a easy way to create "cascading" generators.
The callback must respect the following prototype:

Do not free the provided particle.

15.25 void raydium_particle_generator_particles_OnDelete_name (char *gen, void *OnDelete?):

Same as above, but using generator's name.

15.26 void raydium_particle_scale_all(GLfloat scale):

Will scale all particles with scale factor. Use with caution.
Default is obviously 1.

16 Callbacks:

16.1 Introduction:

This file contains many initializations, a few internal callbacks, but
will provides a very important function for end-user, wich will
gives user display function to Raydium: see below

16.2 void raydium_callback_image (void):

Internal use.

16.3 void raydium_callback_set (void):

Internal use.

16.4 void raydium_callback (void (*loop)):

This function will loop over the provided display function, indefinitely.
"loop" must be:

16.5 void raydium_callback_display_set(void (*fdisplay)):

This function will install display callback but don't enter in an infinite loop.
fdisplay is user display function.
"fdisplay" must be:

16.6 void raydium_loop(void):

Run raydium once. This function needs to be called periodically.
This function return after loop completion.
It is usefull to integrate raydium loop in another program.

17 Normals:

17.1 Introduction:

This file provides some usefull functions for normal generation and smoothing.
You can find some more informations about normals at the top of this guide.
It now provide a few functions about tangent vectors smoothing.

17.2 void raydium_normal_generate_lastest_triangle (int default_visu):

Generate normals for the last created triangle (see raydium_vertex_index)
if default_visu is true ( != 0 ), this function will restore "visu"
normals too.

17.3 void raydium_normal_generate_lastest_tangent(void):

Generate tangents for the last created triangle. Internal use.

17.4 void raydium_normal_restore_all (void):

This function restore visu normals with standard ones (raydium_vertex_normal_*)

17.5 void raydium_normal_regenerate_all (void):

This function will regenerate standard and visu normals for the whole
scene (ground, objects, ...).

17.6 void raydium_normal_internal_smooth_generic(char *type,GLuint from, GLuint to,GLfloat *in_x, GLfloat *in_y, GLfloat *in_z,GLfloat *out_x, GLfloat *out_y, GLfloat *out_z):

Internal. Generic smoothing function.

17.7 void raydium_normal_smooth_all (void):

This function will smooth the whole scene, using adjacent vertices.
Note this function can take a lot of time.

17.8 void raydium_normal_smooth_from_to(GLuint from, GLuint to):

Same as above, but only from from vertex to to vertex (excluded).
In other words: will smooth [from;to[

17.9 void raydium_normal_tangent_smooth_all (void):

Same as raydium_normal_smooth_all(), but for tangent vectors.

17.10 void raydium_normal_tangent_smooth_from_to(GLuint from, GLuint to):

Same as raydium_normal_smooth_from_to(), but for tangent vectors.

18 vertices:

18.1 Introduction:

You can create objets at runtime, if needed, using the following functions.
Each of theses functions adds only one vertex so, obviously, you need to
call three time the same function to add one triangle.

18.2 void raydium_vertex_add (GLfloat x, GLfloat y, GLfloat z):

Adds a vertex at (x,y,z).

18.3 void raydium_vertex_uv_add (GLfloat x, GLfloat y, GLfloat z, GLfloat u, GLfloat v):

Same as above, but providing texture mapping informations with u and v.

18.4 void raydium_vertex_uv_normals_add (GLfloat x, GLfloat y, GLfloat z, GLfloat nx, GLfloat ny, GLfloat nz, GLfloat u, GLfloat v):

Same as above, giving vertex's normal with (nx,ny,nz).

19 Land:

19.1 Introduction:

Historically, this file was quite complex, since Raydium was using
his own physic. Now, this file is almost empty, since ODE integration
now provides new landscape functions.

20 Sky and environement boxes:

20.1 Introduction:

Skyboxes are mostly automated.

For now, Raydium will use BOXfront.tga, BOXback.tga, BOXleft.tga,
BOXright.tga, BOXbottom.tga and BOXtop.tga and will draw a
skybox only if fog is disabled (this is not for technical reasons,
but only for realism, just think about it ;)... but you can force
skybox with fog using raydium_sky_force if you really want).

20.2 void raydium_sky_box_cache (void):

As skybox texture are sometimes large files, you can pre-load skybox
with this function. If you don't do it, Raydium will load textures
during the first frame of your application.
Calling this function will automatically define sky as a HDR emitter.
See HDR chapter for more information.

20.3 void raydium_sky_box_render (GLfloat x, GLfloat y, GLfloat z):

Internal use.

20.4 void raydium_sky_sphere_render(GLfloat x, GLfloat y, GLfloat z, int detail):

Internal use.
Calculates and draw the sphere. Also rotate it according the angles or orbit.

20.5 Atmosphere:

Atmosphere are series of effects that intend to make the sky and the atmosphere
of the game more realistic. As this is quite-beta state, only a orbital sky
effect is available right now.
To activate/deactivate this series of effects, you should use:
raydium_sky_atmosphere_enable and raydium_sky_atmosphere_disable
respectively.
If you need to check if the atmosphere is activated or not, use
raydium_sky_atmosphere_check. The rest of the functions are internal
and should not used by normal programs.

20.6 void raydium_sky_atmosphere_enable(void):

turn on the use of atmosphere effects.
This one and _disable function a program should use, the other
raydium_sky_atmosphere_ are internal ones.

20.7 void raydium_sky_atmosphere_disable(void):

turn off the use of atmosphere effects.

20.8 void raydium_sky_atmosphere_render(GLfloat x, GLfloat y, GLfloat z,int detail):

Internal use. This internal function draws the atmosphere effects. Right
now only draws a rotating sphere with a gradient of color (from black to white).
In a future, it will draw multiples layers of sky (with and without textures),
stars, satellites... Maybe rain and snow could be included here also.

20.9 signed char raydium_sky_atmosphere_check(void):

This functions only check if the atmosphere features are been used.
Returns 1 if they are used, else 0.

21 "Internal" informations access:

21.1 void raydium_internal_dump (void):

This function is now systematically called by Raydium at application's exit,
displaying some informations about loaded textures, objects, registered data,
network statistics.

21.2 void raydium_internal_dump_matrix (int n):

Dumps matrix to console.
n values are:

22 Files (generic):

22.1 Introduction:

File support is now splitted in two parts: generic functions and TRI format
specific functions. This chapter talks about generic part, where you'll find
some libc replacements and wrappers, and functions dealing with
"private directory" of the current user.

22.2 void raydium_file_dirname(char *dest,char *from):

Reliable and portable version of libc's dirname function.
This function extracts directory from from filename, and writes it
to dest.
No memory allocation will be done by the function.

22.3 void raydium_file_basename(char *dest,char *from):

Another libc clone, for basename function. Extracts file name from a
path into dest string.

22.4 void raydium_file_ext(char *dest, char *from):

Return the extension of from filename (can be a complete path), without
the . (dot), or an empty string if extension is not found.

22.5 signed char raydium_file_directory_writable(char *path):

Return 1 if path directory is writable, 0 otherwise.

22.6 signed char raydium_file_readable(char *filename):

Return 1 if filename exists and is readable, 0 otherwise.

22.7 void raydium_file_log_fopen_display(void):

Display (console) all filenames that were opened before the call.
--files command line option will call this function at the application's
exit, closed or not.

22.8 FILE *raydium_file_fopen(char *file, char *mode):

Raydium wrapper to libc's fopen function.
This function will:
- Update some stats
- Try to download the file from repositories if no local version is found, or
will try to update the file if asked (--repository-refresh or
repository-force). See R3S on Raydium's Wiki.
- You can disable R3S client (for a "local only" file) adding a 'l'
in mode ("rl" or "rbl" for example).
- Use Raydium paths (see suitable chapter)

22.9 unsigned long raydium_file_sum_simple(char *filename):

This function will generate a very simple checksum on filename.

22.10 unsigned long raydium_file_sum_simple_mode(char *filename,char *mode):

Same as above, but you can pass a fopen mode ("rt", or "rbl" for example).
See raydium_file_fopen() for more informations about mode.

22.11 char * raydium_file_home_path(char *file):

This function will return an absolute file path for file in the home
directory of the current user.
Returned value is a pointer to static memory. Do not free this memory and use
it before any other call to this function, since it will be overwritten.
Example:
for test.cfg, this function will return /home/me/.raydium/test.cfg
See also raydium_init_args_name() if you want to tune this result.

22.12 void raydium_file_home_path_cpy(char *file, char *dest):

Same as above, but you must provide memory with dest.

22.13 char *raydium_file_load(char *filename):

This function loads filename (as a binary file under win32, no matter
under Linux) in a string, and returns its address. You must free this
memory when finished.

22.14 int raydium_file_binary_fgets(char *dest, int max, FILE *stream):

Binary version of LIBC's fgets. Read a maximum of max bytes from
stream, including terminating 0 character, to dest buffer, and stops
at the first 0 found or at EOF.
No memory allocation is done, and string is always terminated by a 0.
Returns the length of the readed string (without terminating 0).

23 Files (TRI format):

23.1 Warning:

It's important to use only functions with raydium_file_* prefix.
All other functions may change or disappear. Upper level functions are
available (see object.c).

23.2 Introduction:

file.c use .tri mesh files (text), available in 4 versions:

1. version 1: providing normals and uv texture mapping informations.
2. version 0: providing uv texture mapping.
3. version -1: only providing vertices.
4. version 2: mesh animation support

Version 1 example file:


You can find the file version on first line, and then data.
Next lines: vertex position (x,y,z), normal (x,y,z), texture mapping (u,v)
and texture (string).

Version 2 files are a bit different, as showed below:


You may have seen that headers are longer for v2 files. You'll find (just
after the version number) how many "anims" are hosted by this file, and how
many vertices are required for one frame. Then you'll find one line per
"anim", with starting frame, ending frame and anim's name.
Then starts a regular tri file ("sub-file", with its own version number)
with ALL concatened frames.

23.3 void dump_vertex_to (char *filename):

This function save all scene to filename (.tri file) in version 1.
Vertice may be sorted.
Please, try to do not use this function.

23.4 void dump_vertex_to_alpha (char *filename):

Now useless and deprecated.

23.5 int raydium_file_set_textures (char *name):

Internal use.
This function analyze texture filename, and search for extended multitexturing
informations (u,v and another texture).

23.6 void read_vertex_from (char *filename):

Loads filename. Again, avoid use of this function.

24 File path:

24.1 Introduction:

When raydium_file_fopen() is called, by Raydium or by an application,
the Path API is used to search the file.
When the file is open for writing, Raydium will check if the current working
directory is writable. If this is not the case, Raydium will try to write the
file in the user home directory (~/.appname/data/), and will create it if
needed.
For reading, Raydium will also use the current directory first, and then
will search in a list of directories of your choice (see example below).
The user home directory is registered by default in this list.

If the '/' character is present in the requested filename, the path system
is disabled and regular fopen() behavior is used.

24.2 Example of directory registering::

24.3 int raydium_path_find_free(void):

Internal (search a free path slot).

24.4 signed char raydium_path_ext(char *dir, char *ext):

Register dir directory for files with ext extension.
Return 0 when it fails.

24.5 signed char raydium_path_add(char *dir):

Register dir directory.
Return 0 when it fails.

24.6 signed char raydium_path_write(char *dir):

Change the writing directory to dir directory. You should probably also
register this new directory, using raydium_path_add().

24.7 signed char raydium_path_string_from(char *str):

Reset all registrations (only current directory stays) and replace it with the
provided formated string. Here it is an example for such string:


(do not include line feeds and replace 'X' by '*')

This string is based an the example at the top of this chapter.

24.8 int raydium_path_string_to(char *out):

Dumps all registrations to out string.

24.9 void raydium_path_resolv(char *in, char *out, char mode):

Internal (find the best absolute path for the requested file).

24.10 void raydium_path_dump(void):

Dumps read and write paths to console.

24.11 void raydium_path_reset(void):

Reset all registrations.
You should probably better use raydium_path_string_from().

24.12 void raydium_path_write_local_deny(signed char deny):

By default, Raydium always tries to write in the local directory (binary's
directory, in other words), and if it's not possible, did it in the registered
writing directory. Using this function (with deny=1) will force Raydium to use
the second option each time. Then Raydium will never write to local directory.

24.13 void raydium_path_init(void):

Internal.

25 Camera:

25.1 Introduction:

Raydium provides camera management functions, allowing the coder to
move camera with very simple functions, even for complex moves.
You have to place your camera once per frame (not more, not less).

"look_at" style functions can be affected by raydium_camera_look_at_roll
global variable, if needed.

A few words about camera path: Take a look to a .cam file if you want to
understand this simple file format, but you probably only need the cam.c
application, dedicated to camera path creation.

Some camera functions are provided by physics module, see suitable chapter.

25.2 void raydium_camera_vectors (GLfloat * res3):

This function will return two vectors (2 * 3 * GLfloat), giving the camera
orientation (front vector and up vector). At this day, the up vector is
always the same as the world up vector, even if the camera is rotated
or upside down (and yes, this MUST be corrected :).

Designed for internal uses, before all.

25.3 void raydium_camera_internal_prepare(void):

Internal use. (pre)

25.4 void raydium_camera_internal (GLfloat x, GLfloat y, GLfloat z):

Internal use. (post)

25.5 void raydium_camera_place (GLfloat x, GLfloat y, GLfloat z, GLfloat lacet, GLfloat tangage, GLfloat roulis):

Sets the camera at (x,y,z) position, and using (lacet,tangage,roulis)
as rotation angles.

25.6 float *raydium_camera_get_data(void):

Function to get the data of the camera in an array of 6 floats.
The first 3 values are the position like x,y,z in universal coordinates.
The next 3 are the rotation angles like r,s,t in degrees and universal orientation.
example:

Returned data is related to the current frame.

25.7 void raydium_camera_look_at (GLfloat x, GLfloat y, GLfloat z, GLfloat x_to, GLfloat y_to, GLfloat z_to):

Sets the camera at (x,y,z) position, and looks at (x_to,y_to,z_to).

25.8 void raydium_camera_replace (void):

You'll need to reset camera position and orientation after each object drawing.
If this is unclear to you, read the "example" section, below.

You will need to make your own 3D transformations (GLRotate, GLTranslate,
...) to draw your objects, or you can use the following function.

25.9 void raydium_camera_replace_go (GLfloat * pos, GLfloat * R):

This function will replace the camera, as raydium_camera_replace(),
but will place "3D drawing cursor" at position pos (3 GLfloat) with
rotation R (4 GLfloat quaternion).

No eulers (rotx, roty, rotz) version of this function is provided for now..
Do you really need it ?

25.10 Example of camera use:

1. place camera
2. move "drawing cursor" to object's place
3. draw object
4. reset camera to initial place (the one given at step 1)
5. move "drawing cursor" to another object's place
6. draw another object
7. [...]

Steps 4 and 5 can be done with raydium_camera_replace_go().

25.11 void raydium_camera_rumble(GLfloat amplitude, GLfloat ampl_evo, GLfloat secs):

Camera (any type) will rumble for secs seconds, with amplitude (radians).
This amplitude will be incremented of ampl_evo every second (negative
values are allowed for ampl_evo).
An amplitude is always positive.

25.12 void raydium_camera_smooth (GLfloat px, GLfloat py, GLfloat pz, GLfloat lx, GLfloat ly, GLfloat lz, GLfloat zoom, GLfloat roll, GLfloat step):

Smooth style clone of raydium_camera_look_at.
Roll is given by roll and not global variable raydium_camera_look_at_roll
as for regular look_at function.
zoom is the requested FOV.
Play with step to modify smoothing level of the movement. A good way to use
this function is the following usage :

25.13 void raydium_camera_path_init (int p):

Internal use.

25.14 void raydium_camera_path_init_all (void):

Internal use.

25.15 int raydium_camera_path_find (char *name):

Lookups path's id using filename name.
This function will not try to load a camera path if it's not found, and
will return -1.

25.16 int raydium_camera_path_load (char *filename):

Obvious : use this function to load a camera path.

25.17 void raydium_camera_path_draw (int p):

Draws p camera path, as red lines. This must be done at each frame.

25.18 void raydium_camera_path_draw_name (char *path):

Same as above, but using camera path's name.

25.19 signed char raydium_camera_smooth_path (char *path, GLfloat step, GLfloat * x, GLfloat * y, GLfloat * z, GLfloat * zoom, GLfloat * roll):

Returns the (x,y,z) point of the camera path for step step, using
provided zoom (FOV) and roll angle.
It's important to note that step is a float.
Mostly for internal use.

25.20 void raydium_camera_path_reset(void):

Next smooth call will be instantaneous.

25.21 void raydium_camera_smooth_path_to_pos (char *path, GLfloat lx, GLfloat ly, GLfloat lz, GLfloat path_step, GLfloat smooth_step):

"Camera on path looking at a point".
Simple raydium_camera_smooth version: give a path name, a "look_at"
point (lx,ly,lz), a current step, anda smooth_step time
factor (see raydium_camera_smooth example above).

25.22 void raydium_camera_smooth_pos_to_path (GLfloat lx, GLfloat ly, GLfloat lz, char *path, GLfloat path_step, GLfloat smooth_step):

"Camera on point looking at a path".
Same style as previous function.

25.23 void raydium_camera_smooth_path_to_path (char *path_from, GLfloat path_step_from, char *path_to, GLfloat path_step_to, GLfloat smooth_step):

"Camera on a path looking at another path".
Same style as previous functions.

25.24 void raydium_viewport_init(void):

Init of raydium_viewport array to support up to
RAYDIUM_VIEWPORT_MAX viewport

25.25 void raydium_viewport_create (char * name,int tx,int ty):

Create a texture for saving viewport display
Texture size tx and ty must be related with final displayed
viewport size.

25.26 void raydium_viewport_enable(char * name):

Direct all render operations to dedicated viewport.
Advanced camera feature as sound/rumble are desactivated during viewport render.

25.27 void raydium_viewport_save(void):

Copy viewport rendering to texture buffer.
Render operations return to normal state, with normal camera behavior.

25.28 void raydium_viewport_draw(char * name, GLfloat tx,GLfloat ty,GLfloat sx,GLfloat sy):

Draw contents of name viewport to screen
tx,ty are lower left corner in screen percents.
sx,sy are size in screen percents.

25.29 void raydium_camera_freemove(int move):

This function is a fast & easy way to create a working camera that can move
with keys and can be rotated with the mouse, like a usual camera in a
First Person Shooter(FPS) game.
Its sources could be also interesting as an example of implementation of this
kind of camera, since this function can be a bit limited if you want to do
complex things.
You can modify the global variables raydium_camera_freemove_sensibility
and raydium_camera_freemove_speed, mouse sensibility (3 default) and
movement speed (0.1 default) respectively.
If move is RAYDIUM_CAMERA_FREEMOVE_FIXED, camera is only placed and fixed.
Else if move is RAYDIUM_CAMERA_FREEMOVE_NORMAL camera position and orientation are updated with Mouse/Keyboard.

25.30 void raydium_camera_orbitmove(float x, float y, float z, float x_to, float y_to, float z_to):

Tis functions allow to rotate (in fact orbit) around a certain point
(x_to,y_to,z_to). The distance of the point xyz to the camera is
calculated into the function, you just have to give a initial position
for the camera (x,y,z).
Then the distance will be kept while you are orbiting.

26 Objects:

26.1 Introduction:

With the following functions, you can easily draw and manage
mesh objects (.tri file).

26.2 GLint raydium_object_find (char *name):

Lookups an object by its name. This function will return -1 if the
object's not found, and will not try to load the .tri file.

26.3 signed char raydium_object_isvalid(int obj):

Internal use, but you can call this function if you want to verify if an
object id is valid (in bounds).

26.4 GLint raydium_object_find_load (char *name):

Same as above (raydium_object_load), but will try to load object.

26.5 void raydium_object_reset (GLuint o):

Internal use. Do not call.

26.6 int raydium_object_load (char *filename):

Load filename as a .tri file, and returns corresponding id, or
-1 in case of error.

26.7 void raydium_object_draw (GLuint o):

Draws o (index) object, using current matrixes.

26.8 void raydium_object_draw_name (char *name):

Same as above, but you only have to provide object's name (".tri file").
If this object was not already loaded, this function will do it for you.

26.9 void raydium_object_translate(GLuint obj,GLfloat tx,GLfloat ty,GLfloat tz):

Modify object center

26.10 void raydium_object_deform (GLuint obj, GLfloat ampl):

Early devel state. Useless as is.

26.11 void raydium_object_deform_name (char *name, GLfloat ampl):

Early devel state. Useless as is.

26.12 GLfloat raydium_object_find_dist_max (GLuint obj):

This function will return will return the distance form (0,0,0)
to the farest point of obj object.

26.13 void raydium_object_find_axes_max (GLuint obj, GLfloat * tx, GLfloat * ty, GLfloat * tz):

This function returns the (maximum) size of the bounding box
of obj (relative to (0,0,0)).

26.14 void raydium_object_find_minmax(GLuint obj, GLfloat *min, GLfloat *max):

Returns min and max values for obj. No memory allocation is done, you must
provide two GLfloat[3] array.

26.15 void raydium_object_find_center_factors(GLuint obj, GLfloat *tx, GLfloat *ty, GLfloat *tz):

Returns "centering" factors for obj. A centered object will return (0,0,0).

26.16 signed char raydium_object_tangent_smooth(GLuint obj):

This function is a small helper for raydium_normal_tangent_smooth_from_to(),
which will smooth all tangent informations for the object, since some shaders
needs it (Normal Mapping for example).

See suitable chapters for more information.

26.17 signed char raydium_object_tangent_smooth_name(char *obj):

Same as above, using object's name.

26.18 void raydium_object_callback(void):

Internal (frame callback).

26.19 Animations:

Raydium now supports mesh animation, thru MD2 (Quake 2) files. Raydium file
format was extended to version 2. If you want to create an animated mesh
for Raydium from a MD2 file, you may use Blender with "import-md2-0.14.py"
script ( by Bob Holcomb, http://67.22.114.230:8082/programming/blender/index.html )
and export it back to a tri file using provided "triEXP-MD2-*.py" script.
All other tasks (loading, transformations, ...) are done the same way as
regular static mesh.

For Raydium, an animation is a set of "anims", and each "anim" is a set
of "frames". Each "anim" gets its own name (see header of a version 2 file
for more informations), and since an animated object may be use for many
players, Raydium provides an "instances" based system: setting things like
anim and frame for an object is done only for one instance of this object.
Instances are always available, no need to create or declare them.
That's all you need to use animation simple API.

26.20 GLint raydium_object_anim_find(int object, char *name):

Lookups an animation by its name. This function will return -1 if the
animation's not found. Mostly for internal use.

26.21 void raydium_object_anim_generate_internal(int object, int instance):

Internal. Transformed mesh generation.

26.22 void raydium_object_anim_frame(int object, int instance, GLfloat frame):

Sets current frame for one instance of object. frame is
automatically bounded and looped.
Warning, change anim before anim's frame.

26.23 void raydium_object_anim_frame_name(char *object, int instance, GLfloat frame):

Same as above, but using object's name.

26.24 void raydium_object_anim(int object, int instance, int anim):

Sets current anim for one instance of object.
Again, change anim before anim's frame.

26.25 void raydium_object_anim_name(char *object, int instance, char *anim):

Same as above, but using object's name and anim's name.

26.26 void raydium_object_anim_instance(int object, int instance):

With this function, you must set what instance will be drawn when
raydium_object_draw() will be called with object argument.

Default is set to instance 0.

26.27 void raydium_object_anim_instance_name(char *object, int instance):

Same as above, but using object's name.

26.28 void raydium_object_anim_automatic(int object, int anim, GLfloat factor):

With this function, you can set an automatic frame increment for a specific
anim of an object. This increment is based on frame time and factor.

26.29 void raydium_object_anim_automatic_name(char *object, char *anim, GLfloat factor):

Same as above, but using object's name and anim's name.

26.30 "Punctually" anims:

When using animations, you're switching for an "anim" to another, and an
"anim" will loop forever. "Punctually" support will allow you to set a
default "anim" for an object and to do switch punctually to another "anim",
and automatically return back to default value when this "anim" is finished,
usefull for animations like jumps, kick, ...

26.31 void raydium_object_anim_default(int object, int anim):

This function will set default anim for object.

26.32 void raydium_object_anim_punctually(int object, int anim, int instance):

This function will trigger a punctually anim for object's instance.

26.33 void raydium_object_anim_punctually_name(char *object, char *anim, int instance):

Same as above, but with object's name.

26.34 signed char raydium_object_anim_ispunctually(int object, int instance):

Will return true (1) if object is currently running a punctually animation,
or false (0) otherwise.

26.35 signed char raydium_object_anim_ispunctually_name(char *object, int instance):

Same as above, but with object's name.

27 Initialization:

27.1 Introduction:

This file is mainly designed for internal uses, but there's anyway
some interesting functions.

27.2 char *raydium_version(void):

Return Raydium Engine version as a static string. Format is "x.yyy".
You can also find defines for this, named RAYDIUM_MAJOR (x)
and RAYDIUM_MINOR (yyy).

27.3 void raydium_init_lights (void):

Internal use. Must be moved to light.c.

27.4 void raydium_init_objects (void):

Internal use. Must be moved to object.c.

27.5 void raydium_init_key (void):

Internal use. Must be moved to key.c.

27.6 void raydium_init_reset (void):

This function is supposed to reset the whole Raydium engine:
textures, vertices, lights, objects, ...
Never tested yet, and probaly fails for many reasons when called more than
one time.

27.7 void raydium_init_engine (void):

Internal use. Never call this function by yourself, it may cause
huge memory leaks.

27.8 int raydium_init_load(char *filename):

This function is used to load a configuration file, filename, and then it
will do automatically all initialization of the application (window size,
title, lights, skybox, ...)

The filename config file must follow the "variable=value;" pattern, one
variable per line. It allows comments (with double slash). See chapter about
text file parsing for more information about syntax.

If the file does not exists (local or R3S servers), Raydium will create a
default one.

A list of all settings will follow here, soon.

It returns 1 if the load process ends correctly, or 0 is something was wrong.

28 Command Line Interface:

28.1 Introduction:

Here, you'll find a few functions to deal with command line
interface of Raydium.
Here is a list of supported options:

Graphics:
window Define window rendering.
fullscreen Define Fullscreen rendering.

xinerama-fullscreen Select Xinerama FullScreen? render windows.
xinerama-screen Select Screen for render windows.

filter Define texture filter type (none,bilinear,trilinear,aniso).
max-aniso Define Anisotropic filter level to max value according to hardware capacity.
compress Enable texture compression.

Joystick:
joydev Define Jostick number used by raydium.
evdev Define Force FeedBack? peripherial (linux only).

Video / WebCam?:
video-device Define Video device (WebCam? ...) used by live Api.
video-size Define default video Size 640x480, 320x240 ...

Network:
name Set player name for network application.
ode-rate Set physics sample rate for networked application.

Console:
consoletexture Console texture background.
consolefont Console font.

Path and files:
home Setting raydium global home directory.
path Define list of media path.
write-path Define destination directory for media file.
files List all opened files.
logfile Define logfile name.
history Console History file name.

Initialisation Scripts:
autoexec Php script executed just after engine initialization.
autoexec2 php script executed when raydium_callback is called.

Repository:
repository-disable Disable getting media files form repository.
repository-refresh Refresh files form repository even if local file exist.
repository-force Force Repository use.
rayphp Path of rayphp php scripts.

Misc:
regs Dump registers.

28.2 int raydium_init_cli_option(char *option, char *value):

This function will search command line option.
If this option is found, the functions stores any argument to value and
returns 1.
The function will return 0 if option is not found.

Example (search for: --ground)

28.3 int raydium_init_cli_option_default(char *option, char *value, char *default_value):

Same as above, but allows you to provide a default value (default) if
the option is not found on command line.

28.4 void raydium_init_internal_homedir_find(char *):

Internal use.

28.5 void raydium_init_args(int argc, char * *argv):

You must use this function, wich send application arguments to Raydium
and external libs (GLUT, OpenAL, ...).
This must be done before any other call to Raydium.
Example:

28.6 void raydium_init_args_name(int argc, char * *argv, char *app_name):

Same as above, but with application short name. This string is used to
build things like runtime configuration directory name (~/.raydium/ by default).
Use this wrapper if you don't want to share your configuration with Raydium.

29 Signals:

29.1 Quickview:

There almost nothing to said about signals management, except that Raydium
will try to catch SIGINT signal (sended by CTRL+C sequence, for example).
There's nothing else for now, but we plan a user callback for this signal.

30 Sound and music:

30.1 Introduction:

The Raydium sound API is pretty easy to use and there's only need to use a
few functions to make your program ouput sounds or music.

On top of this, there are a bunch of functions to modify the sound behavior.

Raydium uses OpenAL and OggVorbis? for its sounds and musics, for a basic
use of our sound API you only need to know one thing: OpenAL uses buffers
for its sounds and you need to be able to address the sounds separately.
For this we use ALuint in our code. Each buffer is associated to a source,
we have an array of all available sources and then, you only need to have
a simple int that acts as an index in this array. See below for more
informations.

Music is readed thru libogg, streamed from disk. If you want to play an
OGG audio track, the only thing you've to do is to call the suitable function.
You can use raydium_sound_music_eof_callback if needed. This event is
fired when sound track ends, allowing you to switch to another file.
Prototype for this callback is int callback(char *new_track), allowing
you to do something like strcpy(new_track,"foobar.ogg"); return 1;.
Return 0 if you do not want to switch to another audio file (this will stops
music playback).
Another callback is available, raydium_sound_music_changed_callback, fired
just after a music track switch, allowing you to get new informations from the
new stream, such as artist, album and title. See raydium_sound_load_music()
for more informations about this.

This document is not an alternative to OpenAL papers, and only provides
informations about Raydium's interface to OpenAL.
See specifications here: http://www.openal.org/documentation.html

30.2 void raydium_sound_verify (char *caller):

This functions checks if any error occured during last OpenAL operation.
You don't have to call this function by yourself, since every function of
this API will do it.

30.3 int raydium_sound_Array3IsValid(ALfloat *a):

Since OpenAL is very sensitive to malformed values, this function is used
internally to check consistency of provided ALfloat arrays.

30.4 void raydium_sound_InitSource (int src):

Internal use.

30.5 int raydium_sound_LoadWav (const char *fname):

This function tries to load the fname wav file into a buffer, if
successful, it returns the source id, else 0.

30.6 int raydium_sound_SourceVerify (int src):

Internal id checks.

30.7 int raydium_sound_SetSourceLoop (int src, signed char loop):

Modifies the loop property of the src source (loops if loop is non-zero,
default value for a source is "true").
Returns 0 if ok, -1 if error.

30.8 int raydium_sound_GetSourcePitch (int src, ALfloat * p):

Returns current pitch for src source.

30.9 int raydium_sound_SetSourcePitch (int src, ALfloat p):

Sets pitch for src source.
Current OpenAL spec is not clear about pitch's limits. Raydium will
clamp values to to ]0,2] interval.

30.10 int raydium_sound_GetSourceGain (int src, ALfloat * g):

Returns current gain ("volume") for src source.

30.11 int raydium_sound_SetSourceGain (int src, ALfloat g):

Sets gain ("volume") for src source.
Current OpenAL spec is not clear about pitch's limits. Raydium do not allows
negative values, but no upper limit is set.
Warning: some OpenAL implementations will provide strange gain curves. More
work is needed on this issue.

30.12 int raydium_sound_SetSourcePos (int src, ALfloat Pos[]):

Sets 3D position of src source.
Pos is a 3 * ALfloat array.

30.13 int raydium_sound_SetSourcePosCamera(int src):

Sets 3D position of src source on the current camera position.

30.14 int raydium_sound_GetSourcePos (int src, ALfloat * Pos[]):

Returns current 3D position of src source.
Pos is a 3 * ALfloat array.

30.15 int raydium_sound_SetSourceDir (int src, ALfloat Dir[]):

Sets 3D direction of src source.
Dir is a 3 * ALfloat array.

30.16 int raydium_sound_GetSourceDir (int src, ALfloat * Dir[]):

Returns current 3D direction of src source.
Dir is a 3 * ALfloat array.

30.17 int raydium_sound_SetSourceVel (int src, ALfloat Vel[]):

Sets 3D velocity of src source.
Vel is a 3 * ALfloat array.

30.18 int raydium_sound_GetSourceVel (int src, ALfloat * Vel[]):

Returns current 3D velocity of src source.
Vel is a 3 * ALfloat array.

30.19 void raydium_sound_SetListenerPos (ALfloat Pos[]):

Sets 3D position of listener.
This is done automatically by Raydium, each frame, using camera informations
Pos is a 3 * ALfloat array.

30.20 void raydium_sound_GetListenerPos (ALfloat * Pos[]):

Returns current 3D position of listener.
Pos is a 3 * ALfloat array.

30.21 void raydium_sound_SetListenerOr (ALfloat Or[]):

Sets 3D orientation of listener.
This is done automatically by Raydium, each frame, using camera informations
Or is a 3 * ALfloat array.

30.22 void raydium_sound_GetListenerOr (ALfloat * Or[]):

Returns current 3D orientation of listener.
Or is a 3 * ALfloat array.

30.23 void raydium_sound_SetListenerVel (ALfloat Vel[]):

Sets 3D velocity of Listener.
Vel is a 3 * ALfloat array.

30.24 void raydium_sound_GetListenerVel (ALfloat * Vel[]):

Returns current 3D velocity of Listener.
Vel is a 3 * ALfloat array.

30.25 void raydium_sound_init (void):

Internal use.

30.26 int raydium_sound_SourcePlay (int src):

Plays the src source.
If src was already in "play" state, the buffer is rewinded.
Returns 0 if ok, -1 if error.

30.27 int raydium_sound_SourceStop (int src):

Stops the src source.
Returns 0 if ok, -1 if error.

30.28 int raydium_sound_SourcePause (int src):

Will pause the src source.
Returns 0 if ok, -1 if error.

30.29 int raydium_sound_SourceUnpause (int src):

src will restart playback after being paused.
Returns 0 if ok, -1 if error.

30.30 signed char raydium_sound_IsPlaying(int src):

Returns true (1) if src is playing, false (0) if stopped or invalid.

30.31 void raydium_sound_close (void):

Internal use.

30.32 int raydium_sound_load_music (char *fname):

Opens fname OGG music file and prepairs Raydium for playing it.
The music will be automatically played after a call to this function.
This function will use R3S (data repositories) if needed.
To switch to another audio track, simply call again this function.
Send NULL or an empty string to cancel music playback.
Returns 0 if ok, -1 if error

See also raydium_sound_music_eof_callback at the top of this chapter.

You can get OGG informations from raydium_sound_music_info, using
its members:

30.33 void raydium_sound_music_info_init(void):

Internal use. Will reset infos.

30.34 void raydium_sound_music_info_refresh(void):

Internal use. Will flush infos from disk to raydium_sound_music_info.

30.35 void raydium_sound_music_callback (void):

Internal use.

30.36 void raydium_sound_callback (void):

Internal use.

30.37 void raydium_sound_source_fade(int src, ALfloat len):

This function will fade down source src over len seconds.
Since gain is not linear, you may have to play a bit with len to
find the correct value for you.
Use source 0 for music source.

30.38 Sound API Example:

30.39 void raydium_sound_source_fade_to(int src, ALfloat len, char *to):

Same as above, but plays to file at the end of the fade.
Warning: Works only for "music" source (src = 0).

31 Timecalls:

31.1 Concept:

As you may already know, in a real time application (as a game), you need
to control in-game time evolution.
For example, you cannot increment a car position by 1 at each frame since
it will generate an irregular scrolling (a frame is never rendered within
the same time as the previous or the next one).

Raydium supports timecalls, wich are a great solution for this problem.
Usage is very simple: write a simple function, and ask Raydium to call it
at the desired rate.

31.2 Constraints:

There is an important risk with timecalls: infinite loops.
If a callback is long, it may take more CPU time than ig should, as in this
very simple example:

foo() is a function, taking 200 ms for his own execution. If you ask for
a 6 Hz execution, Raydium will execute foo() six times on the first frame,
taking 1200 ms. On the next frame, Raydium will need to execute foo() 7
times (the asked 6 times, and one more for the 200 ms lost during the last
frame), taking 1400 ms, so 8 times will be needed for the next frame, then 9, ...

So you need to create callbacks as short as possible, since long callbacks
may cause a game freeze on slower machines than yours. (1 FPS syndrom)

31.3 Hardware devices and methods:

Raydium must use a very accurate system timer, and will try many methods:
/dev/rtc , gettimeofday() (Linux only) and
QueryPerformanceCounter? for win32.

gettimeofday() will use a CPU counter and is extremely accurate.
It's far the best method. (0.001 ms accuracy is possible)

/dev/rtc is quite good, and Raydium will try to configure RTC at
RAYDIUM_TIMECALL_FREQ_PREFERED rate (8192 Hz by default), but may
require a "/proc/sys/dev/rtc/max-user-freq" modification:
echo 8192 > /proc/sys/dev/rtc/max-user-freq

You may want to look at common.c for interesting defines about timecalls.

31.4 void raydium_timecall_raydium (GLfloat step):

Internal Raydium callback.

31.5 float raydium_timecall_internal_w32_detect_modulo(int div):

Internal, WIN32 only: Returns timer resolution for div divisor.

31.6 int raydium_timecall_internal_w32_divmodulo_find(void):

Internal, WIN32 only: Detects the best timer divisor for the current CPU.

31.7 unsigned long raydium_timecall_devrtc_clock (void):

Internal, Linux only: Reads and return RTC clock.

31.8 unsigned long raydium_timecall_clock (void):

Returns current "time".
The variable raydium_timecall_clocks_per_sec contains the number
of clock "ticks" per second, and may help you here.

31.9 signed char raydium_timecall_devrtc_rate_change (unsigned long new_rate):

Internal, Linux only: Modifies RTC clock rate.

31.10 void raydium_timecall_devrtc_close (void):

Internal, Linux only: Will close RTC clock.

31.11 unsigned long raydium_timecall_devrtc_init (void):

Internal, Linux only: Will open RTC clock.

31.12 int raydium_timecall_detect_frequency (void):

Internal: This function will find the best timer available for current
platform, and adjust properties to your hardware (rate, divisor, ...).

31.13 void raydium_timecall_init (void):

Internal use.

31.14 int raydium_timecall_add (void *funct, GLint hz):

There is two sort of timecalls with Raydium:

1. Standard ones:

void function(void) will be called 800 times per second.

2. Elastic timed ones:

void function(float step) will be called for each frame, with a
"step factor" as argument. In the above example, a 160 Hz game will call
fun