next_inactive up previous


Raydium API Reference

CQFD Corp.

24/10/2003


Contents

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) and mingw 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, a list of many 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 for basic defines:

#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

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

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:

  1. *raydium_vertex_* : these tables will simply contains vertices coordinates
  2. *raydium_vertex_normal_* : vertices normals. Raydium will maintain two distinct normal tables, and this one will be used for calculations.
  3. *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.
  4. *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.

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

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.

1.3.11 particles

Particles and explosions are in early release stage and not documented yet.

2 Maths

2.1 introduction to trigo.c

This section is mostly desgined for internal uses, but provides some usefull maths functions

2.2 Details

2.2.1 GLfloat raydium_trigo_cos(GLfloat i)

Obvious.

2.2.2 GLfloat raydium_trigo_sin(GLfloat i)

Obvious.

2.2.3 GLfloat raydium_trigo_cos_inv(GLfloat i)

Inverse cos.

2.2.4 GLfloat raydium_trigo_sin_inv(GLfloat i)

Inverse sin.

2.2.5 raydium_trigo_abs(A)

Absolute value (defined as a macro for now).

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 Details

3.2.1 void raydium_log(unsigned 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')

raydium_log(``You are player %i, %s'',player_number,player_name);

For now, this function writes to the parent terminal and the in-game console, with ``Raydium: `` string prefix.

4 Random

4.1 Introduction to random.c

These functions deals with random number generation.

4.2 Details

4.2.1 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.2.2 GLfloat raydium_random_pos_1(void)

``positive, to one'': 0 <= res <= 1.

4.2.3 GLfloat raydium_random_neg_pos_1(void)

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

4.2.4 GLfloat raydium_random_0_x(GLfloat x)

``zero to x'': 0 <= res <= x

5 Fog

5.1 Introduction to fog.c

Fog is broken in current releases !

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 triangle displayed at the same time.

5.2 Details

5.2.1 void raydium_fog_enable(void)

Obvious.

Note: use this function, and not OpenGL one !

5.2.2 void raydium_fog_disable(void)

Obvious.

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

5.2.4 void raydium_fog_mode(void)

Do not use.

6 Window managment

6.1 Introduction to window.c

Some important functions, used for window creation and managment.

6.2 Details

6.2.1 void raydium_window_create(GLuint tx, GLuint ty,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.

6.2.2 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.2.3 void raydium_window_view_update(void)

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

7 Capture

7.1 capture.c : quick overview of void raydium_capture_frame(char *filename)

Easy: call this function, and it will generate an uncompressed TGA with the current frame.

This function will failed if frame size if not ``standard'', mostly after a frame resize.

8 Background, frame clearing

8.1 background.c

8.1.1 void raydium_background_color_change(GLfloat r, GLfloat g, GLfloat b, GLfloat a)

Will change raydium_background_color array and apply this modification, changing the frame background color (and fov color, obviously).

8.2 clear.c

8.2.1 void raydium_clear_frame(void)

This function will clear the current frame, and initialize the next one (timecalls, camera, ...)

8.2.2 void raydium_clear_color_update(void)

Use this function if you've changed raydium_background_color by hand. (in facts, you may use raydium_background_color_change)

9 Lights

9.1 Introduction to Raydium light system (light.c)

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.

9.2 Details

9.2.1 void raydium_light_enable(void)

Obvious, as usual.

9.2.2 void raydium_light_disable(void)

Obvious.

9.2.3 GLuint raydium_light_to_GL_light(GLuint l)

Probably useless for end user. (internal uses)

9.2.4 void raydium_light_on(GLuint l)

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

9.2.5 void raydium_light_off(GLuint l)

Turns ``l'' off.

9.2.6 void raydium_light_switch(GLuint l)

Obvious, no ?

Switch from ``on'' to ``off'', etc ...

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

9.2.8 void raydium_light_update_intensity(GLuint l)

Updates raydium_light_intensity[l] changes to hardware.

9.2.9 void raydium_light_update_all(GLuint l)

Updates intensity,position and color.

9.2.10 void raydium_light_move(GLuint l,GLfloat *vect)

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

Unlike most functions in this chapter, raydium_light_move will not send the modification to the hardware during his call.

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

9.2.11 void raydium_light_reset(GLuint l)

This function will restore all defaults for ``l'' light.

9.2.12 void raydium_light_blink_internal_update(GLuint l)

Useless for end-user.

9.2.13 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'')

9.2.14 void raydium_light_callback(void)

Useless for end-user.

10 Keyboard & keys

10.1 Introduction to key.c

Keyboard API is already described at the top of this guide.

Nothing important here.

10.2 Details

10.2.1 void raydium_key_normal_callback(int key, int x, int y)

Internal callback.

10.2.2 void raydium_key_special_callback(int key, int x, int y)

Internal callback.

10.2.3 void raydium_key_special_up_callback(int key, int x, int y)

Internal callback.

11 Mouse

11.1 Introduction to mouse.c

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

11.2 Details

11.2.1 void raydium_mouse_hide(void)

Hides mouse cursor.

11.2.2 void raydium_mouse_show(void)

Shows mouse cursor.

11.2.3 void raydium_mouse_move(int x, int y)

Moves cursor to (x,y) position (in pixel).

Ex moves cursor at window center: raydium_mouse_move(raydium_window_tx/2, raydium_window_ty/2);

11.2.4 void raydium_mouse_clic_callback(int but,int state,int x,int y)

Internal callback.

11.2.5 void raydium_mouse_move_callback(int x, int y)

Internal callback.

12 Textures

12.1 Introduction to texture.c

For now, Raydium can only manipulate 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 now supports materials with a simple ``rgb(r,g,b)'' string as texture name, where r, g and b are 0 <= x <= 1 (floats).

Texture clamping and multitexturing are supported by Raydium, but only used internaly for now. If you're interested, have a look to source code.

12.2 Details

12.2.1 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 fail.

12.2.2 GLuint raydium_texture_load_erase(char *filename, GLuint to_replace)

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

12.2.3 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).

12.2.4 char raydium_texture_current_set_name(char *name)

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

12.2.5 GLuint raydium_texture_find_by_name(char *name)

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

12.2.6 void raydium_texture_filter_change(GLuint filter)

This function will change all filters at anytime. Please note that this function will reload all textures and can be very slow.

raydium_texture_filter_change(RAYDIUM_TEXTURE_FILTER_BILINEAR) // will switch all textures to bilinear filter.

13 Rendering

13.1 Introduction to render.c

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

It' obvious for me that many parts of this code have to be rewritten (tips: slow, buggy, old, ... :)

13.2 Details

13.2.1 void raydium_rendering_from_to(GLuint from, GLuint to)

Renders to - from vertice starting at ``from''. Probably useless for end-user.

13.2.2 void raydium_rendering(void)

Same as above, but renders all.

13.2.3 void raydium_rendering_finish(void)

You must call this function when your frame is finished, as late as possible, since this function will flush 3D hardware intructions.

14 Particles and Explosions

14.1 Introduction to particle.c

Mostly undocumented, will be rewritten, one day... (color support, evolution-over-time option, and a lot better implementation)

Will use ``flare.tga'' for now.

14.2 Details

14.2.1 void raydium_explosion_add(GLfloat x, GLfloat y, GLfloat z, GLfloat vx, GLfloat vy, GLfloat vz, GLfloat dispersion, GLuint ttl, GLfloat dens_perc, GLfloat grav)

Will create an explosion, at (x,y,z), with an initial vector of (vx,vy,vz), a dispersion factor, a ttl time to live, a dens_perc density factor ( 0 < x <= 1 as float), and an acceleration factor of grav used for gravity simulation.

15 Callbacks

15.1 Introduction to callback.c

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.

15.2 Details

15.2.1 void raydium_callback(void (*loop) )

This function will loop over the provided display function, indefinitely.

``loop'' must be: void loop(void)

16 Normals

16.1 Introduction to normal.c

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.

16.2 Details

16.2.1 void raydium_normal_generate_lastest_triangle(int default_visu)

Generate normal for the last created triangle (see raydium_vertex_index)

if default_visu is true ( != 0 ), this function will restore ``visu'' normals too.

16.2.2 void raydium_normal_restore_all(void)

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

16.2.3 void raydium_normal_regenerate_all(void)

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

16.2.4 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 Vertices

17.1 Introduction to vertex.c

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.

17.2 Details

17.2.1 void raydium_vertex_add(GLfloat x, GLfloat y, GLfloat z)

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

17.2.2 void raydium_vertex_uv_add(GLfloat x, GLfloat y, GLfloat z,GLfloat u, GLfloat v)

Same as above, but you can provide texture mapping informations with u and v.

17.2.3 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).

18 Land

18.1 Introduction to land.c

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

18.2 Details

18.2.1 void raydium_land_draw_water(GLfloat phase, GLfloat ampl, GLfloat periode, int sub, char *texture)

Probably broken.

19 Sky and environement boxes

19.1 Introduction to sky.c

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 ;)... You can force skybox with fog using raydium_sky_force (set it to true).

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

20 ``Internal'' informations access

20.1 internal.c : void raydium_internal_dump(void)

This function is now systematically called by Raydium at application exit, displaying some informations about loaded textures and objects.

21 Files

21.1 Warning

THIS FUNCTIONS WILL CHANGE, so use upper level functions (see object.c).

21.2 Introduction to file.c

file.c use .tri mesh files, available in three versions:

  1. version 1: providing normals and uv texture mapping informations.
  2. version 0: providing normals.
  3. version -1: only providing vertices.
Version 1 example file:

1

5.1 15.75 -3.82 0.0000 0.0000 -1.0000 0.5158 0.5489 rgb(0.5,0.5,0.5)

6.3 11.75 -3.82 0.0000 0.0000 -1.0000 0.5196 0.5365 rgb(0.5,0.5,0.5)

5.0 11.75 -3.82 0.0000 0.0000 -1.0000 0.5158 0.5365 rgb(0.5,0.5,0.5)

[...]

Text file.

First line: file version

Next lines: vertex position (x,y,z), normal (x,y,z), texture mapping (u,v) and texture (string).

21.3 Details

21.3.1 void dump_vertex_to(char *filename)

This function save all scene to filename (.tri file) in version 1.

21.3.2 void read_vertex_from(char *filename)

Loads filename. Again, avoid use of this function.

22 Camera

22.1 Introduction to camera.c

Raydium provides camera management functions, allowing the end-user to move camera with very simple functions, even for complex moves.

You have to place your camera once per frame.

22.2 Details

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

22.2.2 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).

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

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

22.2.5 Example:

  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().

23 Objects

23.1 Introduction to object.c

With the following functions, you can easily draw an object (.tri file).

23.2 Details

23.2.1 int raydium_object_find(char *name)

Returns index of the ``name'' object. Unlike texture functions, if object is not found, this function will not load it.

23.2.2 int raydium_object_load(char *filename)

Loads ``filename'' object.

23.2.3 void raydium_object_draw(GLuint o)

Draws ``o'' (index) object.

23.2.4 void raydium_object_draw_name(char *name)

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

24 Initialization

24.1 Introduction to init.c

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

24.2 Details

24.2.1 void raydium_init_reset(void)

This function is supposed to reset the whole Raydium engine: textures, vertices, lights, objects, ...

Never tested yet :)

24.2.2 void raydium_init_args(int argc, char **argv)

You must use this function, wich send application arguments to Raydium and external libs (GLUT, OpenAL, ...).

Example:

int main(int argc, char **argv)

{

raydium_init_args(argc,argv);

[...]

25 Signals

25.1 Quickview

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.

26 Sound and music

26.1 Introduction to sound.c

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.

26.2 Details

26.2.1 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 quits properly the main program.

26.2.2 void raydium_sound_SetSourceLoop(int src, 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.

26.2.3 void raydium_sound_GetSourcePitch(int src, ALfloat *p)

Returns the actual pitch value of src source into p.

Returns 0 if ok, -1 if error.

26.2.4 void raydium_sound_SetSourcePitch(int src, ALfloat p)

Sets the p pitch value of src source.

Returns 0 if ok, -1 if error.

26.2.5 void raydium_sound_GetSourceGain(int src, ALfloat *g)

Returns the actual gain value of src source into g.

Returns 0 if ok, -1 if error.

26.2.6 void raydium_sound_SetSourceGain(int src, ALfloat g)

Sets the g gain value of src source.

Returns 0 if ok, -1 if error.

26.2.7 void raydium_sound_GetSourcePos(int src, ALfloat *Pos[])

Returns the actual position of src source into Pos. Pos is an array[3] of ALfloat.

Returns 0 if ok, -1 if error.

26.2.8 void raydium_sound_SetSourcePos(int src, ALfloat Pos[])

Sets the Pos position of src source. Pos is an array[3] of ALfloat.

Returns 0 if ok, -1 if error.

26.2.9 void raydium_sound_GetSourceDir(int src, ALfloat *Dir[])

Returns the actual direction of src source into Dir. Dir is an array[3] of ALfloat.

Returns 0 if ok, -1 if error.

26.2.10 void raydium_sound_SetSourceDir(int src, ALfloat Dir[])

Sets the Dir direction of src source. Dir is an array[3] of ALfloat.

Returns 0 if ok, -1 if error.

26.2.11 void raydium_sound_GetSourceVel(int src, ALfloat *Vel[])

Returns the actual velocity of src source into Vel. Vel is an array[3] of ALfloat.

Returns 0 if ok, -1 if error.

26.2.12 void raydium_sound_SetSourceVel(int src, ALfloat Vel[])

Sets Vel velocity of src source. Vel is an array[3] of ALfloat.

Returns 0 if ok, -1 if error.

26.2.13 void raydium_sound_GetListenerPos(ALfloat *Pos[])

Acts like the raydium_sound_Get/SetSource... but this time for the listener.

26.2.14 void raydium_sound_SetListenerPos(ALfloat Pos[])

Acts like the raydium_sound_Get/SetSource... but this time for the listener.

26.2.15 void raydium_sound_GetListenerOr(ALfloat *Or[])

Returns the actual orientation of the listener into Or. Or is an array[6] of ALfloat like this:

{x,y,z, x2,y2,z2}

ATvector UPvector

26.2.16 void raydium_sound_SetListenerOr(ALfloat Or[])

Sets the Or orientation of the listener. Or is an array[6] of ALfloat like this:

{x,y,z, x2,y2,z2}

ATvector UPvector

26.2.17 void raydium_sound_GetListenerVel(ALfloat *Vel[])

Acts like the raydium_sound_Get/SetSource... but this time for the listener.

26.2.18 void raydium_sound_SetListenerVel(ALfloat Vel[])

Acts like the raydium_sound_Get/SetSource... but this time for the listener.

26.2.19 void raydium_sound_SourcePlay(int src)

Plays the src source.

Returns 0 if ok, -1 if error.

26.2.20 void raydium_sound_SourceStop(int src)

Stops playing the src source.

Returns 0 if ok, -1 if error.

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

Returns 0 if ok, -1 if error.

26.3 Example

int sound 
sound=raydium_sound_LoadWav("explo.wav"); 
raydium_sound_SetSourceLoop(sound,0); 
[...] 
if(explosion) raydium_sound_SourcePlay(sound);

27 Timecalls

27.1 Introduction to timecalls.c

27.1.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 than 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.

27.1.2 Constraints

There is an important risk with timecalls: infinte loops.

If a callback is long, it may take more CPU time than he would, 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)

27.1.3 Hardware devices and methods

Raydium must use a very accurate system timer, and will try many methods:

/dev/rtc , gettimeofday() (linux only) and GetTickCount() 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

GetTickCount() is (for now) the only timer available for windows, allowing a 100 Hz timer in most cases.

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

27.2 Details

27.2.1 void raydium_timecall_add(void *funct, GLint hz)

There is two sort of timecalls with Raydium:

  1. Standard ones:
    raydium_timecall_add(function,800); 
    void function(void) will be called 800 times per second.
  2. Elastic timed ones: 
    raydium_timecall_add(function,-80) 
    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 function with step = 0.5, but step = 2.0 for a 40 Hz game.
A standard timecalls will use void(void) function and a positive hertz argument, as an elasitc one will use void(float) and negative hertz argument.

28 Network

28.1 Introduction to network.c

Raydium supports networking via UDP/IP, providing high level functions for multiplayer game development.

Raydium servers are limited to 256 clients for now.

You will find in network.c a set of functions and vars dedicated to networked games: players names, event callbacks, UDP sockets, broadcasts, ... All this is ready to use. As it's not done in the introduction of this guide, We will explain here some variables defined in index.c file.

#define RAYDIUM_NETWORK_PORT 29104

#define RAYDIUM_NETWORK_PACKET_SIZE 230

#define RAYDIUM_NETWORK_TIMEOUT 5

#define RAYDIUM_NETWORK_PACKET_OFFSET 4

#define RAYDIUM_NETWORK_MAX_CLIENTS 8

#define RAYDIUM_NETWORK_MODE_NONE 0

#define RAYDIUM_NETWORK_MODE_CLIENT 1

#define RAYDIUM_NETWORK_MODE_SERVER 2 

Here, we can find network port declaration (Raydium will use only one port, allowing easy forwarding if needed), default timeout (unit: second), and the three mode possible for a Raydium application (none [no network is used], client and server).

But there is also two other very important defines: packet size (unit: byte) and max number of clients.. This is important because Raydium uses UDP sockets, and UDP sockets required fixed length packets, and as you need to set packet size as small as possible (for obvious speed reasons), you must calculate you maximum information packet size (players position, for example), multiply it by RAYDIUM_NETWORK_MAX_CLIENTS,and add RAYDIUM_NETWORK_PACKET_OFFSET wich represent the required header of the packet.

It's more easy than it seems, look:

My game will support 8 players.

I will send players state with 3 floats (x,y,z).

My packet size must be: 8*3*sizeof(float)+RAYDIUM_NETWORK_PACKET_OFFSET = 100 bytes.

Please, do not change packet offset size, since Raydium will use it for packet header.

#define RAYDIUM_NETWORK_DATA_OK 1

#define RAYDIUM_NETWORK_DATA_NONE 0

#define RAYDIUM_NETWORK_DATA_ERROR -1 

This three defines are used as network functions result:

if(raydium_network_read_flushed(&id,&type,buff)==RAYDIUM_NETWORK_DATA_OK)

{

[...] 

#define RAYDIUM_NETWORK_PACKET_BASE 10 

In most network functions, you will find a ``type'' argument, used to determine packet ``goal''. This type is 8 bits long (256 possible values), but Raydium already uses some of them. So you can use RAYDIUM_NETWORK_PACKET_BASE as a base for your own types:

#define NORMAL_DATA RAYDIUM_NETWORK_PACKET_BASE

#define BALL_TAKEN (DATA+1)

#define SCORE_INFO (DATA+2)

#define HORN       (DATA+3)

[...]

Your own player id (0<= id <= RAYDIUM_NETWORK_MAX_CLIENTS). Read only:

int raydium_network_uid; 

Current network mode (none, client, server). Read only:

char raydium_network_mode; 

Boolean used to determine client state (connected or not), read only:

char raydium_network_client[RAYDIUM_NETWORK_MAX_CLIENTS];

example: if(raydium_network_client[4]) draw_player(4); 

Can be used by a server to send data to his clients. Read only:

struct sockaddr raydium_network_client_addr[RAYDIUM_NETWORK_MAX_CLIENTS]; 

Players names, read only:

char raydium_network_name[RAYDIUM_NETWORK_MAX_CLIENTS][RAYDIUM_MAX_NAME_LEN];

OnConnect and OnDisconnect events (server only):

void * raydium_network_on_connect;

void * raydium_network_on_disconnect;

You can place your owns callbacks [ void(int) ] on these events, as in this example:

void new_client(int client)

{

 raydium_log(``New player: %s'', raydium_network_name[client]);

}

[...]

int main(int argc, char **argv)

 {

 [...]

 raydium_network_on_connect=new_client;

 [...]

28.2 Details

28.2.1 void raydium_network_write(struct sockaddr *to, int from, char type,char *buff)

Obviously, this function will send data.

If you're a client, you don't need to determine to field, as the only destination is the server, so you can use NULL, for example. If you're a server, you can use raydium_network_client_addr[] array.

As a client, from argument is generally your own uid (raydium_network_uid), but you can use any other player number if needed. As a server, from field is useless, since you are the only machine able to send data to clients.

As you may expect, type field is used to determine packet's type. You can use any (8 bits) value greater or equal to RAYDIUM_NETWORK_PACKET_BASE.

Finally, buff is a pointer to data's buffer. This buffer must be RAYDIUM_NETWORK_PACKET_SIZE long, and can be cleared or re-used after this call.

28.2.2 void raydium_network_broadcast(char type,char *buff)

Sends data over network.

Obviously, from network point of vue, only a server can broadcast (to his clients).

When a client needs to broadcast (from the game point of vue) some informations (his own position, for example), he must send this information to server, and the server will broadcast it.

This function uses the same arguments as previous one, except to and from, not needed here.

28.2.3 char raydium_network_read(int *id, char *type, char *buff)

Reads next packet from network (FIFO) stack.

This function uses the same arguments as previous ones, and returns data availability: RAYDIUM_NETWORK_DATA_OK, 
RAYDIUM_NETWORK_DATA_NONE or  
RAYDIUM_NETWORK_DATA_ERROR.

28.2.4 char raydium_network_read_flushed(int *id, char *type, char *buff)

Reads last packet from network stack.

All previous packets will be ignored, only the newest packet will be read (if any).

As you may miss some some important informations, you can use netcalls (see below) if you want to capture packets with a particular type, even with flushed reading.

28.2.5 char raydium_network_netcall_add(void *ptr, int type)

You can add a netcall (ptr) for a particular packet type.

In most cases, with multiplayer games, there is a main data stream (players state, for example: position, rotation, ...) and some random events: broadcast message, horn, player death, ...

With Raydium, you can read the main data stream with raydium_network_read_flushed(), and configure network callbacks (netcalls) on random events (using packet type).

Netcalls signature is: void(int type, char *buff)

As you may configure the same callback function for multiples packet types, this type is passed to your function, with the temporary buff buffer. You can extract from field from packet if needed.

28.2.6 char raydium_network_set_socket_block(int block)

By default, Raydium uses non-blocking network sockets: if you tried to read from a socket, you will receive a [...]DATA_NONE or [...]DATA_OK answer. You can change this behaviour with this function, using argument block as a boolean. With block != 0, raydium_network_read() will wait until data some data is ready.

28.2.7 char raydium_network_server_create(void)

Will transform you application into a server, accepting new clients instantaneously.

28.2.8 char raydium_network_client_connect_to(char *server)

This function will try to connect your application to server (hostname or ip address).

WARNING: For now, this call could be endless ! (server failure while connecting).

This function will succed returning 1 or 0 otherwise.

You are connected instantaneously, and you must start sending data before server timeout (defined by RAYDIUM_NETWORK_TIMEOUT). You player number can be found with raydium_network_uid variable, as said before.

29 OSD (On Screen Display)

29.1 Introduction to osd.c

Raydium provides some high level function for ``On Screen Display'', as string drawing (2D and 3D), application's logo and mouse cursor.

In most cases, these functions must be called after any other object drawing function, to avoid overlapping.

29.2 Details

29.2.1 void raydium_osd_color_change(GLfloat r, GLfloat g, GLfloat b)

This function will change the font color for the next raydium_osd_printf* calls.

As usual: 0 <= (r,g and b) <= 1.

29.2.2 void raydium_osd_alpha_change(GLfloat a)

Same as above, but will change font transparency.

29.2.3 void raydium_osd_color_rgba(GLfloat r, GLfloat g, GLfloat b, GLfloat a)

This is a mix of raydium_osd_color_change and raydium_osd_alpha_change.

29.2.4 void raydium_osd_color_ega(char hexa)

This function will change font color with the corresponding hexadecimal code (as a char: '0' to 'F') in the standard EGA palette.

Here it is this palette:

hexa color
0 black
1 blue
2 green
3 cyan
4 red
5 purple
6 brown
7 white
8 grey
9 light blue
A light green
B light cyan
C light red
D light purple
E light yellow
F light white

29.2.5 void raydium_osd_printf(GLfloat x, GLfloat y, GLfloat size, GLfloat spacer,char *texture, unsigned char *format, ...)

This function is an OpenGL equivalent to the standard ``printf'' C function.

Here you are a simple example:

strcpy(version,''^Ctest 0.1^F'');

[...]

raydium_osd_printf(2,98,16,0.5,"font2.tga","- %3i FPS - tech demo %s for Raydium %s, CQFD Corp.",last_fps,version,raydium_version);

29.2.6 void raydium_osd_printf_3D(GLfloat x, GLfloat y, GLfloat z, GLfloat size, GLfloat spacer,char *texture, unsigned char *format, ...)

Same as above, but you can place your text in your application 3D space, using x, y and z values.

29.2.7 void raydium_osd_logo(char *texture)

Will draw a logo for the current frame with texture filename.

29.2.8 void raydium_osd_cursor_set(char *texture,GLfloat xsize, GLfloat ysize)

This function will set mouse cursor with texture filename and with (xsize,ysize) size (percent of screen size).

You should use a RGBA texture for better results.

example:

raydium_osd_cursor_set("BOXcursor.tga",4,4);

30 In-game console

30.1 Introduction to console.c

This chapter introduce the first version of the Raydium console, allowing applications to take user keyboard input (game commands, chat, ...) and to display some informations to this console.

The user can call the console using ``the key below esc''.

30.2 Details

30.2.1 int raydium_console_gets(char *where)

This function will try to read last user input, returning 1 (true) if some data were available, and will copy these data to where.

Returns 0 otherwise.

You should probably call this function each frame, since no callback was still written.

30.2.2 void raydium_console_line_add(char *format, ...)

This function will add a line in the console output. Please, look at raydium_osd_printf function for a format explanation.

Please note that raydium_log will use this function automaticaly.

30.2.3 void raydium_console_event(void)

Send a ``move !'' event to console, changing his state (lowered / hidden).

We will probably add a argument to this function in a near future.

31 Joystick, pads and force feedback

31.1 Introduction to joy.c

Raydium supports Joysticks, joypads, steering wheels, force feedback devices, keyboard emulation, for Linux only.

Since API could change during Win32 integration, there is no particular documentation about this subject.

char raydium_joy_button[RAYDIUM_BUTTONS_MAX_BUTTONS];

GLfloat raydium_joy_x;

GLfloat raydium_joy_y;

GLfloat raydium_joy_z;

int raydium_joy;

Buttons are booleans, joy x,y and z are -1 <= (x,y,z) <= 1 and 0 means ``center''.

31.2 Details

31.2.1 void raydium_joy_key_emul(void)

Emulate keyboard (directional pad) with joy, if any.

31.2.2 void raydium_joy_ff_tremble_set(GLfloat period, GLfloat force)

Send tremble effect to Force Feedback device for a determined period, at a particular force. (no units yet).

32 Miscalleneous

32.1 License

None for now (public domain), and will switch to GPL soon.

32.2 About CQFD Corp Raydium Active Contribution Team (tm) (c)

batcox, Blue Prawn, Cocorobix, FlexH, Jimbo, manproc, neub, RyLe, whisky, willou, Xfennec.

32.3 Todo

ODE Integration, network modification, rendering core update, and many many other things !...

32.4 Links

http://www.cqfd-corp.org (CQFD homesite)
http://raydium.cqfd-corp.org (Raydium home)
http://wvs.cqfd-corp.org (Web Version System: public mini CVS like for Raydium)
http://memak.cqfd-corp.org (MeMak forum: ``a game using Raydium'', french)
Mailto: cqfd@cqfd-corp.org
Mailto: xfennec@cqfd-corp.org

32.5 Greets

Many !

More to come ;)

About this document ...

Raydium API Reference

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.70)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir4260XYDqUP/lyx_tmpbuf0/api_wvs.tex

The translation was initiated by xfennec on 2004-02-22


next_inactive up previous
xfennec 2004-02-22