Creating models

When you need to draw large models it is rather expensive to call all the different drawing functions again and again in every step. To avoid this you can create models. A model consists of a number of drawing primitives and shapes. Once a model is created you can draw it at different places with just one function call. Models can also be loaded from a file or saved to a file.

Before giving the different functions available there is one important point: the handling of textures. As described earlier, texture are taken from sprites and backgrounds. The indices of the textures can be different at different moments. As a result models do not contain any texture information. Only when you draw a model you provide the texture. So you can only use one texture in a model. If you need more textures you must either combine them in one (and carefully deal with the texture coordinates) or you must use multiple models. The advantage of this is that you can draw the same model easily with different textures.

For creating, loading, saving, and drawing models, the following functions exist:

d3d_model_create() Creates a new model and returns its index. This index is used in all other functions dealing with models.
d3d_model_destroy(ind) Destroys the model with the given index, freeing its memory.
d3d_model_clear(ind) Clears the model with the given index, removing all its primitives.
d3d_model_save(ind,fname) Saves the model to the indicated file name.
d3d_model_load(ind,fname) Loads the model from the indicated file name.
d3d_model_draw(ind,x,y,z,texid) Draws the model at position (x,y,z). texid is the texture that must be used. Use -1 if you do not want to use a texture. If you want to rotate or scale the model you can use the transformation routines described before.

For each primitive function there is an equivalent to add it to a model. The functions have the same arguments as before except that each has a first argument the index of the model, and no texture information is provided.

d3d_model_primitive_begin(ind,kind) Adds a 3D primitive to the model of the indicated kind: pr_pointlist, pr_linelist, pr_linestrip,pr_trianglelist,pr_trianglestrip or pr_trianglefan.
d3d_model_vertex(ind,x,y,z) Add vertex (x,y,z) to the model.
d3d_model_vertex_color(ind,x,y,z,col,alpha) Add vertex (x,y,z) to the model, with its own color and alpha value.
d3d_model_vertex_texture(ind,x,y,z,xtex,ytex) Add vertex (x,y,z) to the model with position (xtex,ytex) in the texture.
d3d_model_vertex_texture_color(ind,x,y,z,xtex,ytex,col,alpha) Add vertex (x,y,z) to the model with texture and color values.
d3d_model_vertex_normal(ind,x,y,z,nx,ny,nz) Add vertex (x,y,z) to the model, with normal vector (nx,ny,nz).
d3d_model_vertex_normal_color(ind,x,y,z,nx,ny,nz,col,alpha) Add vertex (x,y,z) to the model, with normal vector (nx,ny,nz), and with its own color and alpha value.
d3d_model_vertex_normal_texture(ind,x,y,z,nx,ny,nz,xtex,ytex) Add vertex (x,y,z) to the model, with normal vector (nx,ny,nz), with texture position.
d3d_model_vertex_normal_texture_color(ind,x,y,z,nx,ny,nz,xtex,ytex,col,alpha) Add vertex (x,y,z) to the model, with normal vector (nx,ny,nz), with texture and color values.
d3d_model_primitive_end(ind) End the description of the primitive in the model.

Besides primitives you can also add basic shapes to the models. Again the functions look almost the same but with a model index and without texture information:

d3d_model_block(ind,x1,y1,z1,x2,y2,z2,hrepeat,vrepeat) Adds a block shape to the model.
d3d_model_cylinder(ind,x1,y1,z1,x2,y2,z2,hrepeat,vrepeat,closed,steps) Adds a cylinder shape to the model.
d3d_model_cone(ind,x1,y1,z1,x2,y2,z2,hrepeat,vrepeat,closed,steps) Adds a cone shape to the model.
d3d_model_ellipsoid(ind,x1,y1,z1,x2,y2,z2,hrepeat,vrepeat,steps) Adds a ellipsoid shape to the model.
d3d_model_wall(ind,x1,y1,z1,x2,y2,z2,hrepeat,vrepeat) Adds a wall shape to the model.
d3d_model_floor(ind,x1,y1,z1,x2,y2,z2,hrepeat,vrepeat) Adds a floor shape to the model.

Using models can considerable speed up the graphics in your 3D games and you should use them whenever you can.