rl.h

Windows上的MUD客户端程序

 * Get the wireframe options.
 */
int			RLDeviceGetWireframeOptions(RLDevice);

/*
 * Set the texture quality for the device.  Default is RLTextureNearest.
 */
RLError			RLDeviceSetTextureQuality(RLDevice, RLTextureQuality);

/*
 * Get the texture quality for the device.  Returns -1 on error.
 */
RLTextureQuality	RLDeviceGetTextureQuality(RLDevice);

/*
 * Set the colour model for the device.
 */
RLError			RLDeviceSetColourModel(RLDevice, RLColourModel);

/*
 * Get the colour model for the device.  Returns -1 on error.
 */
RLColourModel		RLDeviceGetColourModel(RLDevice);

/*
 * Set the gamma correction value for the device.
 */
RLError			RLDeviceSetGamma(RLDevice, RLValue);

/*
 * Return the current gamma value for the device.
 */
RLValue                  RLDeviceGetGamma(RLDevice);

/*
 * Set the number of shades in a ramp of colours used for shading.
 * Must be a power of 2.  Default is 32.
 */
RLError			RLDeviceSetShades(RLDevice, int);

/*
 * Get the number of shades in a ramp of colours used for shading.
 * Returns -1 on error.
 */
int			RLDeviceGetShades(RLDevice);

/*
 * Create a viewport on dev with screen coordinates (x, y) to (x +
 * width, y + height).  The viewport displays objects in the scene of
 * camera with the view direction and upvector taken from camera.
 */
RLViewport		RLCreateViewport(RLDevice dev,
					 RLFrame camera,
					 int x, int y,
					 int width, int height);

/*
 * Get the device the viewport is associated with
 */
RLDevice		RLViewportGetDevice(RLViewport view);

/*
 * Get the dimensions of a viewport.
 */
int			RLViewportGetX(RLViewport view);
int			RLViewportGetY(RLViewport view);
int			RLViewportGetWidth(RLViewport view);
int			RLViewportGetHeight(RLViewport view);

/*
 * Reconfigure the dimensions of a viewport
 */
RLError			RLViewportConfigure(RLViewport view,
						int x, int y,
						int width, int height);


/*
 * Clear the contents of the viewport.
 */
RLError			RLViewportClear(RLViewport view);

/*
 * Force an area of the viewport to be updated.  The specified area will
 * be copied to the screen at the next call to RLDeviceUpdate.
 */
RLError			RLViewportForceUpdate(RLViewport view,
					      int x1, int y1,
					      int x2, int y2);

/*
 * Set the projection type for the viewport.  The default value is
 * RLProjectPerspective.
 */

typedef enum _RLProjectionType {
    RLProjectPerspective,
    RLProjectOrthographic
} RLProjectionType;

RLError			RLViewportSetProjection(RLViewport view,
						RLProjectionType type);

/*
 * Get the current projection type for the viewport.
 */
RLProjectionType	RLViewportGetProjection(RLViewport view);

/*
 * Render a hierarchy in the viewport.
 */
RLError			RLViewportRender(RLViewport view, RLFrame scene);

/*
 * Transform the vector *s in world coordinates to screen coordinates
 * returning the result in *d.
 */
RLError			RLViewportTransform(RLViewport view,
					    RLVector4d* d,
					    RLVector* s);

/*
 * Transform the vector *s in screen coordinates to world coordinates
 * returning the result in *d.
 */
RLError			RLViewportInverseTransform(RLViewport view,
						   RLVector* d,
						   RLVector4d* s);

/*
 * Change the camera for the viewport.
 */
RLError			RLViewportSetCamera(RLViewport view,
					    RLFrame camera);

/*
 * Get the current camera for the viewport.
 */
RLFrame			RLViewportGetCamera(RLViewport view);

/*
 * Change the front clipping plane for the viewport.  Defaults to 1.0
 */
RLError			RLViewportSetFront(RLViewport view, RLValue front);

/*
 * Return the current value for the viewport's front clipping plane.
 */
RLValue                  RLViewportGetFront(RLViewport view);

/*
 * Change the back clipping plane for the viewport.  Defaults to 100.0
 */
RLError			RLViewportSetBack(RLViewport view, RLValue back);

/*
 * Return the current value for the viewport's back clipping plane.
 */
RLValue                  RLViewportGetBack(RLViewport view);

/*
 * Change the field of view for the viewport.  Defaults to 0.5
 */
RLError			RLViewportSetField(RLViewport view, RLValue field);

/*
 * Return the current value for the viewport's field of view.
 */
RLValue                  RLViewportGetField(RLViewport view);

/*
 * Define the front clipping plane of the viewing frustum by giving the
 * coordinates of the four sides, relative to the camera's z axis.
 */
RLError			RLViewportSetPlane(RLViewport view,
					   RLValue left, RLValue right,
					   RLValue bottom, RLValue top);

/*
 * Get the front clipping plane of the viewing frustum.
 */
RLError			RLViewportGetPlane(RLViewport view,
					   RLValue* left, RLValue* right,
					   RLValue* bottom, RLValue* top);

/*
 * If this is set to TRUE, then the same horizontal and vertical scaling
 * factor is used to scale the viewing volume into the larger dimension
 * of the window.  Otherwise, different scaling factors are used to scale
 * the viewing volume exactly into the window.  This would normally be used
 * with RLViewportSetPlane to support banding.  The default setting is TRUE.
 */
RLError			RLViewportSetUniformScaling(RLViewport view, int);

/*
 * Returns TRUE if the viewport scales uniformly, otherwise FALSE.
 */
int			RLViewportGetUniformScaling(RLViewport view);


typedef struct _RLFaceInfo {
    RLVector	position;
    RLFace	face;
    RLMesh	mesh;
    RLFrame	frame;
} RLFaceInfo;

/*
 * Find the closest face with x, y screen coordinates.  The position, face
 * mesh and frame are returned in *info.  Returns RLNotFound if there
 * is no face with the given coordinates.  Note that this will not
 * call the application's error handler when it returns RLNotFound.
 */
RLError			RLViewportFindFace(RLViewport view,
					   RLFaceInfo* info,
					   int x, int y);

/*
 * Find a list of faces with x, y screen coordinates, sorted by depth.
 * The number of faces is returned in *count_return and a list of
 * RLFaceInfo structures is allocated and returned in *info_return.
 * This memory should be freed with RLFree.
 */
RLError			RLViewportFindFaces(RLViewport view,
					    int* count_return,
					    RLFaceInfo** info_return,
					    int x, int y);

/*
 * Find the closest object with x, y screen coordinates.
 */
RLError			RLViewportFindVisual(RLViewport view,
					     RLVisual* visual_return,
					     RLFrame* frames_return,
					     int x, int y);

/*
 * Find a depth sorted list of objects with x, y screen coordinates.
 */
RLError			RLViewportFindVisuals(RLViewport view,
					      int* count_return,
					      RLVisual** visuals_return,
					      RLFrame** frames_return,
					      int x, int y);

typedef struct _RLPickRecord {
    RLVector	position;
    RLFace	face;
    RLVisual	visual;
    int		frame_count;
    RLFrame*	frames;
} RLPickRecord;

/*
 * Find a depth sorted list of objects (and faces if relavent) which includes
 * the path taken in the hierarchy from the root down to the frame which
 * contained the object.
 */
RLError			RLViewportPick(RLViewport id, int x, int y,
				       int* count_return,
				       RLPickRecord** records_return);

/*
 * Free the information returned by RLViewportPick.
 */
void			RLFreePickRecords(int count, RLPickRecord* records);

/*
 * RL System heartbeat.
 */
RLError			RLTick(void);

/*
 * Create a colour from three components in the range 0-1 inclusive.
 */
RLColour		RLCreateColourRGB(RLValue red,
					  RLValue green,
					  RLValue blue);

/*
 * Create a colour from four components in the range 0-1 inclusive.
 */
RLColour		RLCreateColourRGBA(RLValue red,
					   RLValue green,
					   RLValue blue,
					   RLValue alpha);

/*
 * Get the red component of a colour.
 */
RLValue			RLColourGetRed(RLColour);

/*
 * Get the green component of a colour.
 */
RLValue			RLColourGetGreen(RLColour);

/*
 * Get the blue component of a colour.
 */
RLValue			RLColourGetBlue(RLColour);

/*
 * Get the alpha component of a colour.
 */
RLValue			RLColourGetAlpha(RLColour);

/*
 * Create a new RLFace object with no vertices.
 */
RLFace			RLCreateFace(void);

/* 
 * Add a vertex to a face.
 */
RLError			RLFaceAddVertex(RLFace face,
					RLValue x,
					RLValue y,
					RLValue z);

/*
 * Add a vertex to a face by its index in the containing mesh.  The
 * face must already be in a mesh.
 */
RLError			RLFaceAddVertexAndNormalIndexed(RLFace face,
							int vertex,
							int normal);

/*
 * Set the colour of a face
 */
RLError			RLFaceSetColourRGB(RLFace, RLValue, RLValue, RLValue);
RLError			RLFaceSetColour(RLFace, RLColour);

/*
 * Get the colour of a face.  Returns -1 if there was an error.
 */
RLColour		RLFaceGetColour(RLFace);

/*
 * Get vertex information for a face.  Sets *vertex_count to the
 * number of vertices, *coords to point at a list of RLVectors for
 * the vertex coordinates and *normals to point at a list of RLVectors
 * for the vertex normals.
 * The memory returned in *coords and *normals should be freed with
 * RLFree.
 */
RLError			RLFaceGetVertices(RLFace,
					  int* vertex_count,
					  RLVector** coords,
					  RLVector** normals);

/*
 * Get the number of vertices for a face.  Note that this information
 * is also provided by RLFaceGetVertices.  Returns -1 on error.
 */
int			RLFaceGetVertexCount(RLFace);

/*
 * Get an individual vertex and normal for a face.  Note that this
 * information is also provided by RLFaceGetVertices.  Possible values
 * for which range from 0 to RLFaceGetVertexCount(face) - 1.
 */
RLError			RLFaceGetVertex(RLFace,
					int which,
					RLVector* vertex,
					RLVector* normal);

/*
 * Get the vertex index in a mesh for a given face index.
 * Returns -1 on error.
 */
int			RLFaceGetVertexIndex(RLFace, int which);

/*
 * Get the normal index in a mesh for a given face index.
 * Returns -1 on error.
 */
int			RLFaceGetNormalIndex(RLFace, int which);

/*
 * Get the texture coordinate index in a mesh for a given face index.
 * Returns -1 on error.
 */
int			RLFaceGetTextureCoordinateIndex(RLFace id, int which);

/*
 * Set the texture map for a face.  Pass NULL to remove the texture from
 * the face.
 */
RLError			RLFaceSetTexture(RLFace, RLTexture);

/*
 * Get the texture map for a face.  Returns NULL if there is no texture
 * or if an error occurred.
 */
RLTexture		RLFaceGetTexture(RLFace);

/*
 * Set the texture coordinates of a single vertex in a face.
 * Texture coordinates range from (0,0) for the top left to
 * (1,1) for the bottom right. u or v values higher than 1
 * indicate repetition of the texture
 */
RLError			RLFaceSetTextureCoordinates(RLFace id,
						    int which,
						    RLValue u,
						    RLValue v);

/*
 * Get the texture coordinates of a single vertex in a face.
 * The values are returned in u and v.
 * Texture coordinates range from (0,0) for the top left to
 * (1,1) for the bottom right. u or v values higher than 1
 * indicate repetition of the texture
 */
RLError 		RLFaceGetTextureCoordinates(RLFace,
						    int which,
						    RLValue* u,
						    RLValue* v);

/*
 * Set the material for a face.  Pass NULL to remove the material from
 * the face.
 */
RLError			RLFaceSetMaterial(RLFace, RLMaterial);

/*
 * Get the material for a face.  Returns NULL if there is no material
 * or if an error occurred.
 */
RLMaterial		RLFaceGetMaterial(RLFace);

/*
 * Define the topological properties of the texture coordinates
 * across the face.  The texture can be considered to form either
 * a flat surface of infinite extent, an infinite cylinder with
 * either the u or v coordinate wrapping around or a torus with
 * both u and v wrapping around.  The wrap_u and wrap_v parameters
 * define whether the texture wraps around in the u and v direction
 * respectively.  The default values for wrap_u and wrap_v are FALSE.
 */
RLError RLFaceSetTextureTopology(RLFace face, int wrap_u, int wrap_v);

/*
 * Get the topological properties of a texture when mapped onto the face.
 */
RLError RLFaceGetTextureTopology(RLFace face, int* wrap_u, int* wrap_v);

/*
 * Get a normal vector to the face.
 */ 
RLError			RLFaceGetNormal(RLFace id, RLVector* n);

/*
 * Create a new mesh object with no faces.
 */
RLMesh			RLCreateMesh(void);

/*
 * Load a mesh from a file
 */
RLMesh		RLLoadOldMesh(const char*);
RLMesh		RLLoadMesh(const char*);
RLMesh		RLLoadMeshWithTextures(const char* name,
				       RLTextureNameCallback load_tex_fn,
				       void* arg);

typedef enum _RLXOFFormat {
    RLXOFBinary,
    RLXOFCompressed,
    RLXOFText
} RLXOFFormat;

#define RLXOFSaveNormals		1
#define RLXOFSaveTextureCoordinates	2
#define RLXOFSaveMaterials		4
#define RLXOFSaveTextureNames		8
#define RLXOFSaveAll                    15

/*
 * Save a mesh, using either a binary or a text format, specifying
 * which optional sections to save.
 */
RLError			RLSaveMesh(RLMesh mesh, char* fileName,
		      		   RLXOFFormat format, int save);

/*
 * Add a vertex to the mesh, returning the index of the new vertex.
 * The vertex index can then be used later with
 * RLFaceAddVertexAndNormalIndexed.  Returns -1 on error.
 */
int			RLMeshAddVertex(RLMesh mesh,
					RLValue x, RLValue y, RLValue z);

/*
 * Add a normal to the mesh, returning the index of the new normal.
 * The normal index can then be used later with
 * RLFaceAddVertexAndNormalIndexed.  Returns -1 on error.
 */
int			RLMeshAddNormal(RLMesh mesh,
					RLValue x, RLValue y, RLValue z);

/*
 * Add the face to the mesh. The face is consumed by the mesh and
 * cannot be deleted or added to another mesh.
 */
RLError			RLMeshAddFace(RLMesh mesh, RLFace);

/*
 * Create a face and add it to the mesh.  Equivalent to RLCreateFace()
 * followed by RLMeshAddFace().
 */
RLFace			RLMeshCreateFace(RLMesh mesh);

/*
 * Add a number of faces to a mesh.  For each face, face_data should
 * contain a vertex count followed by the indices into the vertices
 * array of the faces.  If normal_count is non-zero, then face_data
 * should contain a vertex count, followed by pairs of indices, the
 * first into the vertices array and the second into the normals
 * array.
 *
 * If face_count_return is non-null, the number of faces added
 * is returned in *face_count_return.
 *
 * If faces_return is non-null, the faces are returned in
 * *faces_return.  The memory should be freed using
 * RLFree(*faces_return).
 */
RLError			RLMeshAddFaces(RLMesh mesh,
				       int vertex_count,
				       RLVector* vertices,
				       int normal_count,
				       RLVector* normals,
				       int* face_data,
				       int* face_count_return,
				       RLFace** faces_return);

/*
 * Reserve space for a given number of vertices, normals, and faces to
 * be added to the mesh.  This can be used when a large number of
 * face-sets are to be added to the mesh to optimise performance.
 */
RLError			RLMeshReserveSpace(RLMesh mesh,