# libs3d - The S3D API

## Using the s3d library

### Setting s3d up

Install the lib using the usual usual mechanism:

     cmake .
     make
     make install

You might need to have superuser rights in order to do make install. You should now have the server, the library and some applications installed somewhere.

### Getting started

After having s3d installed, you can write your own s3d programs (yeah, that is what this guide is about ;)

     #include <s3d.h>

should be enough to access the 3d functions. If you want to use keyboard interaction, do

     #include <s3d_keysym.h>

for the keycode table. Now you can compile your program with

     bash$  gcc program.c -ls3d -o program
     That wasn't that hard, wasn't it?

## function reference

&libs3d_func;

## Data types

&libs3d_struct; &libs3d_typedef;

## Definitions

### S3D events

This defines the callback format. Each callback should return void and take an argument of struct s3d_evt *. Callbacks can be defined with s3d_set_callback().

S3D_EVENT_OBJ_CLICK

- An object got clicked (when you set the flag S3D_OF_SELECTABLE), buf will contain the object id of the object which got clicked (uint32_t)

S3D_EVENT_KEY

- A key was pressed, buf will contain a keycode. use #include <s3d_keysym.h> to have the keycodes available. buf is a 2 byte unsigned short keycode.

S3D_EVENT_MBUTTON

- A mouse button was clicked. Use struct s3d_but_info on buf to get more info.

S3D_EVENT_NEW_OBJECT

- deprecated, will use S3D_EVENT_OBJ_INFO

S3D_EVENT_OBJ_INFO

- Something happened to an object. This can happen if the camera was moved, the mouse (pointer) was moved or an application appeared/changed in the mcp

S3D_MCP_OBJECT

- As the name suggests, those will only happen to the MCP. This tells it about new/changed application object. struct mcp_object can be used on buf. To be removed in the future.

S3D_MCP_DEL_OBJECT

- As the name suggests, those will only happen to the MCP. This tells it about deleted application object. struct mcp_object can be used on buf. To be removed in the future.

S3D_EVENT_QUIT

- Server sent the quit signal, or the connection was terminated. Usually, this is only processed internally.

    /* a callback handler could look like this: */
    void my_key_handler(struct s3d_evt *event_data)
    {
    	...
    }

### S3D Object Flags

Objects can have several flags to change their behavior in the server and can be set with s3d_flags_on() and s3d_flags_off()

S3D_OF_VISIBLE

- default:off

  Obviously, if this flag is toggled the user can see it, if not it will be hidden. ;)

  When an object is created it's turned off, so you will be able push your geometry data and turn it on after you're done. That avoids flickering and stuff.

S3D_OF_SELECTABLE

- default:off

  When this is toggled on, you will receive click events. Don't use it if you don't need it, it will eat performance.

S3D_OF_POINTABLE

- default:off

  Placeholder for pointer (onmouseover-event enabler) events. Not implemented yet.

## Additional Notes

### About alpha transparency

Alpha transparency works, but polygons don't get ordered in view direction on the server yet. So please don't use this feature yet. If you have an easy idea how to do that with OpenGL please drop me a line.