# s3d_usage

    #include <s3d.h>void s3d_usage

Prints the possible parameter for the client library (which can be passed in s3d_init())

## s3d_init

    #include <s3d.h>int s3d_initint *argcchar ***argvconst char *name

This will initialize the s3d-library and the connection to the Server. It will return 0 on success in server initialization. name specifies the your programs name.

     int main(char argc, char **argv)
     {
             if (!s3d_init(&argc, &argv, "Hello world"))
             {
                     ...
                     s3d_quit();
             }
             return 0;
     }

## s3d_quit

    #include <s3d.h>int s3d_quit

Closes the connection and clears the event-stack. It can also be used to leave the s3d_mainloop().

## s3d_mainloop

    #include <s3d.h>int s3d_mainloopvoid(*)(void) f

Takes a function as argument. It will loop this function until a quit-event is received. You can pass NULL if you have no function to be looped, but its better to sleep some time if you have nothing to do anyway to save cpu-time.

     void mainloop(void)
     {
             usleep(1000); // sleep 1 ms in every cycle
     }
     ...

     s3d_mainloop(mainloop());

## s3d_push_vertex

    #include <s3d.h>int s3d_push_vertexint objectfloat xfloat yfloat z

Pushes a vertex onto the vertex stack. Make sure that you count how many vertices you've pushed because you'll need that for referencing when you push your polygons.

## s3d_push_vertices

    #include <s3d.h>int s3d_push_verticesint objectconst float *vbufuint16_t n

Push some vertices from an array. that's much better for performing than using s3d_push_vertex() if you have a lot of vertices (and that's probably the usual case).

     float vertices[] = { 0.0, 0.0, 0.0,
                          1.0, 2.0, 3.0,
                          3.0, 2.0, 1.0};
     s3d_push_vertices(object, vertices, 3); // pushing 3 vertices

## s3d_push_material

    #include <s3d.h>int s3d_push_materialint objectfloat amb_rfloat amb_gfloat amb_bfloat spec_rfloat spec_gfloat spec_bfloat diff_rfloat diff_gfloat diff_b

Pushes a material for an object. you will have to count them yourself too, as polygons will ask for the material index number. The material properties are given in rgb (red/green/blue) color codes, in float. 0.0 is the minimum, 1.0 is the maximum a color value can be. The specular color is the color which is directly reflected from the light source. The diffuse color is the color which can be seen in the bright side of the object, and the ambience color is the color of the shadow side of the object.

## s3d_pep_material

    #include <s3d.h>int s3d_pep_materialint objectfloat amb_rfloat amb_gfloat amb_bfloat spec_rfloat spec_gfloat spec_bfloat diff_rfloat diff_gfloat diff_b

Overwriting the latest pushed material, overwriting the current value with the specified one. See s3d_pep_materials_a if you want to pep more materials.

## s3d_push_material_a

    #include <s3d.h>int s3d_push_material_aint objectfloat amb_rfloat amb_gfloat amb_bfloat amb_afloat spec_rfloat spec_gfloat spec_bfloat spec_afloat diff_rfloat diff_gfloat diff_bfloat diff_a

Same as s3d_push_material, but color has alpha value added. Use s3d_push_materials_a() if you have a lot of materials to push.

## s3d_push_materials_a

    #include <s3d.h>int s3d_push_materials_aint objectconst float *mbufuint16_t n

Pushes a buffer of materials. Those materials are in the format float[n*12], with

mbuf[n*12 + 0-3] - ambience

mbuf[n*12 + 4-7] - specular

mbuf[n *12 + 8-11] - diffusion values

of each entry. n is the number of materials pushed. The values are in the order r,g,b,a. If you only want to push one material, use the more easy s3d_push_material_a() function.

     // each line has r,g,b,a value
     float bla[24]=
             {1, 0, 0, 1,
              1, 0, 0, 1,
              1, 0, 0, 1,
              0, 1, 1, 1,
              0, 1, 1, 1,
              0, 1, 1, 1};

     s3d_push_materials_a(object, bla, 2); // push a red and a cyan material

## s3d_pep_material_a

    #include <s3d.h>int s3d_pep_material_aint objectfloat amb_rfloat amb_gfloat amb_bfloat amb_afloat spec_rfloat spec_gfloat spec_bfloat spec_afloat diff_rfloat diff_gfloat diff_bfloat diff_a

Overwriting the latest pushed material, overwriting the current value with the specified one, with alpha value in contrast to s3d_pep_material See s3d_push_materials_a if you want to pep more materials.

## s3d_pep_materials_a

    #include <s3d.h>int s3d_pep_materials_aint objectconst float *mbufuint16_t n

Alters the last n pushed materials. See s3d_push_materials_a() for more information how mbuf should look like. Use s3d_pep_material_a() if you only want to alter the latest material.

## s3d_load_materials_a

    #include <s3d.h>int s3d_load_materials_aint objectconst float *mbufuint32_t startuint16_t n

Loads n materials starting from index position start into the material stack. See s3d_push_materials_a for more information about the values in mbuf.

## s3d_push_polygon

    #include <s3d.h>int s3d_push_polygonint objectuint32_t v1uint32_t v2uint32_t v3uint32_t material

Push one polygon on the polygon stack of the object. It takes 3 vertex-index numbers and one material material-index-no. as argument.

     int oid = s3d_new_object();   // create a new object
     s3d_push_vertex(oid, 0.0, 0.0, 0.0);
     s3d_push_vertex(oid, 0.0, 1.0, 0.0);
     s3d_push_vertex(oid, 1.0, 0.0, 0.0);
     s3d_push_material(oid, 0.3, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0);
     s3d_push_polygon(oid, 0, 1, 2, 0);
     // this will create a red polygon

## s3d_push_polygons

    #include <s3d.h>int s3d_push_polygonsint objectconst uint32_t *pbufuint16_t n

As for vertices, you can push arrays of polygons to have greater performance. The pbuf should contain n polygons which consist of 4 uint32_t values of 3 vertices indices and 1 material index.

     uint32_t pbuf[] = { 0, 1, 2, 0};
     int oid = s3d_new_object();   // create a new object
     s3d_push_vertex(oid, 0.0, 0.0, 0.0);
     s3d_push_vertex(oid, 0.0, 1.0, 0.0);
     s3d_push_vertex(oid, 1.0, 0.0, 0.0);
     s3d_push_material(oid, 0.3, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0);
     s3d_push_polygons(oid, pbuf, 1);
     // push one polygon with the pbuf data

## s3d_push_line

    #include <s3d.h>int s3d_push_lineint objectuint32_t v1uint32_t v2uint32_t material

Push one line on the line stack of the object. It takes 2 vertex-index-no, and one material material-index-no. as argument. If you have a lot of lines to push, use s3d_push_lines()

## s3d_push_lines

    #include <s3d.h>int s3d_push_linesint objectconst uint32_t *lbufuint16_t n

Pushing n lines on the line stack of the object, each lbuf has a size of n*3, each entry has the index number of the first vertex, second vertex and material number just as in s3d_push_line().

## s3d_push_texture

    #include <s3d.h>int s3d_push_textureint objectuint16_t wuint16_t h

Adds a new texture with height w and height h on the texture stack.

## s3d_push_textures

    #include <s3d.h>int s3d_push_texturesint objectconst uint16_t *tbufuint16_t n

As for vertices, you can push arrays of textures on the texture stack to have greater performance. The tbuf should contain n texture sizes which consist of 2 uint16_t values for width and height for each texture.

## s3d_pop_vertex

    #include <s3d.h>int s3d_pop_vertexint objectuint32_t n

Deletes the latest n vertices from the vertex stack of the object.

## s3d_pop_polygon

    #include <s3d.h>int s3d_pop_polygonint objectuint32_t n

Deletes the latest n polygon from the polygon stack of the object.

## s3d_pop_material

    #include <s3d.h>int s3d_pop_materialint objectuint32_t n

Deletes the latest n material from the material stack of the object.

## s3d_pop_texture

    #include <s3d.h>int s3d_pop_textureint objectuint32_t n

Deletes the latest n textures from the texture stack of the object.

## s3d_pop_line

    #include <s3d.h>int s3d_pop_lineint objectuint32_t n

Deletes the latest n lines from the line stack of the object.

## s3d_pep_line_normals

    #include <s3d.h>int s3d_pep_line_normalsint objectconst float *nbufuint16_t n

Adds normal information to lines, giving each vertex of a line a normal information. This makes lines somewhat nicer, you'll need that especially when you're going to build wireframe models.

nbuf should contain n * 6 float values, for each vertex a normal vector (x,y,z), and you have 2 vertices for each line so that makes 6 float values per line in total.

## s3d_pep_polygon_normals

    #include <s3d.h>int s3d_pep_polygon_normalsint objectconst float *nbufuint16_t n

Adds normal information to polygons, giving each vertex of a polygon a normal information. With this, you can achieve smoothed edge effects.

nbuf should contain n * 9 float values, for each vertex a normal vector (x,y,z), and you have 3 vertices for each Polygon so that makes 9 float values per Polygon in total. Don't worry if you don't use this, it's kind of hard to calculate and the server will always use some proper normal values (same for every vertex, calculated by the plane which is defined by the 3 points of the polygon.

## s3d_pep_polygon_tex_coord

    #include <s3d.h>int s3d_pep_polygon_tex_coordint objectfloat x1float y1float x2float y2float x3float y3

Pimp the last polygon pushed with some textures coordinates, x and y values for each vertex point respectively. Those values may be between 0 and 1 and are vertex points on the texture defined in the material of the polygon. If you have more polygons which should get a texture, use s3d_pep_polygon_tex_coords()

## s3d_pep_polygon_tex_coords

    #include <s3d.h>int s3d_pep_polygon_tex_coordsint objectconst float *tbufuint16_t n

Pimp the latest n polygons with texture coordinates. tbuf has 6*n float values for its entries, which are supplied in the order as in s3d_pep_polygon_tex_coord()

## s3d_pep_material_texture

    #include <s3d.h>int s3d_pep_material_textureint objectuint32_t tex

Assign the latest material a texture referenced by the index tex. Of course, you will have pushed this texture with s3d_push_texture()

## s3d_pep_vertex

    #include <s3d.h>int s3d_pep_vertexint objectfloat xfloat yfloat z

Alter the latest pushed vertex, overwriting with the supplied values.

## s3d_pep_vertices

    #include <s3d.h>int s3d_pep_verticesint objectconst float *vbufuint16_t n

Alter the latest n pushed vertex. vbuf holds the values which are used to overwrite the old data, n entries with each 3 floats specifying x,y,z of the vertices.

## s3d_pep_line

    #include <s3d.h>int s3d_pep_lineint objectint v1int v2int material

Alter the latest pushed line, overwriting with the supplied values.

## s3d_pep_lines

    #include <s3d.h>int s3d_pep_linesint objectconst uint32_t *lbufuint16_t n

Alter the latest n pushed lines. lbuf holds the values which are used to overwrite the old data, n entries with each 3 uint32_t specifying first, second vertex and material of each line.

## s3d_load_line_normals

    #include <s3d.h>int s3d_load_line_normalsint objectconst float *nbufuint32_t startuint16_t n

Just as s3d_pep_line_normals(), with the difference you won't alter the latest n lines but n lines starting with index start.

## s3d_load_polygon_normals

    #include <s3d.h>int s3d_load_polygon_normalsint objectconst float *nbufuint32_t startuint16_t n

Just as s3d_pep_polygon_normals(), with the difference you won't alter the latest n polygons but n polygons starting with index start.

## s3d_load_polygon_tex_coords

    #include <s3d.h>int s3d_load_polygon_tex_coordsint objectconst float *tbufuint32_t startuint16_t n

Just as s3d_pep_polygon_tex_coords(), with the difference you won't alter the latest n polygons but n polygons starting with index start.

## s3d_load_texture

    #include <s3d.h>int s3d_load_textureint objectuint32_t texuint16_t xposuint16_t yposuint16_t wuint16_t hconst uint8_t *data

This will load an 32bit rgba image supplied in data at position xpos,ypos of the texture tex. The image has the width w and height h. This can be used to update only parts of the texture. It's no problem to supply big textures, as the image will be sent to server in fragments. Of course, you will have created the texture with s3d_push_texture, have an material assigned to the texture with s3d_pep_material_texture() and have your polygons set sane polygon texture coords using s3d_pep_polygon_tex_coord().

## s3d_new_object

    #include <s3d.h>int s3d_new_object

Creates a new object, returning the object id.

Of course, you won't forget to toggle it visible, won't you?

## s3d_del_object

    #include <s3d.h>int s3d_del_objectint oid

Deletes the object referenced by oid.

## s3d_clone

    #include <s3d.h>int s3d_cloneint oid

Clones an already existing object. They get just look the same as the parent-object and will change when the parent-object changes. Cloning especially makes sense if you want to use the same object a lot of times. Move and transform is independent from the parent. The function returns the children object id.

## s3d_clone_target

    #include <s3d.h>int s3d_clone_targetint oidint toid

Changes the clone target of oid to another object (toid). This assumes you've got oid from s3d_clone before.

## s3d_link

    #include <s3d.h>int s3d_linkint oid_fromint oid_to

A linked object will move along with it's link parent. For example if you have a book on a table, you can link the book to the table so the book will "keep on the table" if you move the table around in space. It will also rotate with the table etc.

## s3d_unlink

    #include <s3d.h>int s3d_unlinkint oid

Remove the link of object oid to its target.

## s3d_flags_on

    #include <s3d.h>int s3d_flags_onint objectuint32_t flags

Turn some flags on for object.

If you don't toggle OF_VISIBLE on, you won't see your object. usually you want this. (at least after you *push()d all your content)

## s3d_flags_off

    #include <s3d.h>int s3d_flags_offint objectuint32_t flags

Turn some flags off for object.

## s3d_translate

    #include <s3d.h>int s3d_translateint objectfloat xfloat yfloat z

Move the object to some position in space. when you create an object, it's always located at 0.0 , 0.0, 0.0.

Translation is absolute, not relative!

     s3d_translate(object, 2, 0, 0);
     s3d_translate(object, 4, 0, 0);
     // object will end up at 4,0,0 and not 6,0,0!!

## s3d_rotate

    #include <s3d.h>int s3d_rotateint objectfloat xfloat yfloat z

Rotate an object around the x, y and z-axis respectively. x,y,z may have values between [0,360] degrees.

You will usually only rotate around one axis, leaving the unused fields on 0, I guess. If you want to rotate around more than one axis, please note: The order of the rotation applies is y-axis, x-axis, and then z-axis. You can think of it as the earth position coordinates: x is the longitude, y is the latitude, and z is the rotation at this point of the earth around your bodies axis. (I wonder if that makes it any clearer ;)

Rotate is absolute, not relative!

     s3d_rotate(object, 90,  0, 0);
     s3d_rotate(object, 180, 0, 0);
     // object will be rotated 180 degrees around the x-axis, not 270 degress!

## s3d_scale

    #include <s3d.h>int s3d_scaleint objectfloat s

Scales the object. about factor s. s=1 will be the original size, -1 will mirror it.

s=0 is forbidden and will be ignored! s3d_scale is also absolute, not relative!

## s3d_import_model_file

    #include <s3d.h>int s3d_import_model_fileconst char *fname

Imports an 3d object file and returns the object number. Quite a number of formats are supported, like 3D Studio (.3ds, .prj), Lightwave (.lw, .lwb, .lwo), Quake Models (.md3), or simply everything libg3d supports. :)

Of course, you won't forget to toggle it visible, won't you?

## s3d_open_file

    #include <s3d.h>int s3d_open_fileconst char *fnamechar **pointer

This opens the file fname, setting *pointer to it's memory position. the function will return the size of buffer. you can free() the pointer when you're finished.

## s3d_select_font

    #include <s3d.h>int s3d_select_fontconst char *mask

This selects a font for the s3d_draw_string() function.

Of course, you won't forget to toggle it visible, won't you?

     s3d_select_font("vera"); // will use the vera font face

## s3d_draw_string

    #include <s3d.h>int s3d_draw_stringconst char *strfloat *xlen

Renders the string str with in Truetype format with the height 1, returns the length of the rendered string in *xlen (or set len=NULL to disable this).

     char str="hello world!";
     float len;
     s3d_select_font("vera");
     s3d_draw_string(str, len);

     // not interested in the length? do that: s3d_draw_string(str, NULL);

## s3d_strlen

    #include <s3d.h>float s3d_strlenconst char *str

Returns the length of the string if it were rendered with the currently selected font. That might be useful to estimate the size used for a text and render the background or bounding box before inserting the text.

## s3d_vector_length

    #include <s3d.h>float s3d_vector_lengthconst float vector[]

Calculates and returns the length of the given vector (which should be of the type float[3]). More info on wikipedia http://en.wikipedia.org/wiki/Vector_(spatial)

## s3d_vector_dot_product

    #include <s3d.h>float s3d_vector_dot_productconst float vector1[]const float vector2[]

Calculates and returns the dot product of vector1 and vector2. All vectors should have the format float[3]. More info on wikipedia. http://en.wikipedia.org/wiki/Vector_(spatial)

## s3d_vector_subtract

    #include <s3d.h>void s3d_vector_subtractconst float vector1[]const float vector2[]float result_vector[]

Subtracts vector1 from vector2, writing result into result_vector. All vectors should have the format float[3]. More info on wikipedia. http://en.wikipedia.org/wiki/Vector_(spatial)

## s3d_vector_angle

    #include <s3d.h>float s3d_vector_angleconst float vector1[]const float vector2[]

Calculates and returns the angle between vector1 and vector2. Please note that the resulting angle is between 0 and PI, therefore not covering the whole period! To convert in degrees just do result*180/M_PI. All vectors should have the format float[3]. More info on wikipedia. http://en.wikipedia.org/wiki/Vector_(spatial)

## s3d_angle_to_cam

    #include <s3d.h>float s3d_angle_to_camconst float obj_pos[]const float cam_pos[]float *angle_rad

Given obj_pos and cam_pos in the format float[3], angle_rad about which angle the object should be rotated around the y-axis so that it faces the camera. This might become handy if you have some text floating in space and want it to face the camera. http://en.wikipedia.org/wiki/Vector_(spatial)

## s3d_vector_cross_product

    #include <s3d.h>void s3d_vector_cross_productconst float vector1[]const float vector2[]float result_vector[]

Calculates and returns the cross product of vector1 and vector2. All vectors should have the format float[3]. More info on wikipedia. http://en.wikipedia.org/wiki/Vector_(spatial)

## s3d_push_event

    #include <s3d.h>void s3d_push_eventstruct s3d_evt *newevt

Pushes an event onto the event-stack. Usually you don't need to do this manually.

## s3d_pop_event

    #include <s3d.h>struct s3d_evt *s3d_pop_event

Pops the latest event from the stack. Don't forget to free() both the event and its buffer! Returns a pointer to struct s3d_evt.

## s3d_find_event

    #include <s3d.h>struct s3d_evt *s3d_find_eventuint8_t event

Finds the latest occurrence of an event, giving the event type as argument. Returns a pointer to struct s3d_evt.

## s3d_delete_event

    #include <s3d.h>int s3d_delete_eventconst struct s3d_evt *devt

Deletes an event, the argument is the pointer to the event which is to be deleted (maybe obtained from s3d_find_event).

## s3d_set_callback

    #include <s3d.h>void s3d_set_callbackuint8_t events3d_cb func

Sets a callback for a certain event. this is very useful for event-oriented applications. event callbacks will not interrupt each other or the mainloop.

Defining callbacks will only work after calling s3d_init()

     #include <inttypes.h>

     void obj_click(struct s3d_evt event)
     {
             printf("object id %"PRIu32" got clicked", *((uint32_t *)event->buf));
     }
     ...
     s3d_set_callback(S3D_EVENT_NEW_OBJECT, obj_click);
     // this will tell you when a object got clicked

## s3d_clear_callback

    #include <s3d.h>void s3d_clear_callbackuint8_t event

Clears the callback which is associated with the event.

## s3d_ignore_callback

    #include <s3d.h>void s3d_ignore_callbackuint8_t event

Sets the callback on ignore, that means it won't be queued up for later use. An incoming event of this type will simply be skipped.

## s3d_get_callback

    #include <s3d.h>s3d_cb s3d_get_callbackuint8_t event

Returns the Callback-function of the event.

     struct s3d_evt e;
     ...
     s3d_get_callback(S3D_EVENT_KEY)(e);
     // will call the key-handling function with argument e.

## s3d_process_stack

    #include <s3d.h>void s3d_process_stack

This function goes through all function of the event-stack and will call functions. this is useful when you define a new function but still have a lot of events of this type on the stack.

Deprecated

This is probably obsolete

## s3d_mcp_focus

    #include <s3d.h>int s3d_mcp_focusint object

This is an mcp-only function. It gives focus (for receiving key-strokes etc.) to an app referenced by it's mcp-object-id.

## s3d_net_check

    #include <s3d.h>int s3d_net_check

This functions is for programs which do not employ a mainloop, hence they need to check for new events on their own. Programs like these must make sure to call this function from time to time to convince the server that they did not freeze or bail out.