rl.h

Windows上的MUD客户端程序

/*
 * $Id: RL.H,v 1.3 1995/11/20 22:13:09 jimd Exp $
 *
 * Copyright (c) RenderMorphics Ltd. 1993, 1994
 * Version 1.1
 *
 * All rights reserved.
 *
 * This file contains private, unpublished information and may not be
 * copied in part or in whole without express permission of
 * RenderMorphics Ltd.
 *
 */

#ifndef __RL_H__
#define __RL_H__

#include <stddef.h>

#ifdef __psx__
#ifndef FIXED_POINT_API
#define FIXED_POINT_API
#endif
#ifndef FIXED_POINT_INTERNAL
#define FIXED_POINT_INTERNAL
#endif
#endif

#if defined(__cplusplus)
extern "C" {
#endif

#ifndef TRUE
#define FALSE 0
#define TRUE 1
#endif

typedef struct _RLObject*		RLObject;
typedef struct _RLObject*		RLDevice;
typedef struct _RLObject*		RLViewport;
typedef struct _RLObject*		RLFrame;
typedef struct _RLObject*		RLVisual;
typedef struct _RLObject*		RLMesh;
typedef struct _RLObject*		RLFace;
typedef struct _RLObject*		RLLight;
typedef struct _RLObject*		RLTexture;
typedef struct _RLObject*		RLWrap;
typedef struct _RLObject*		RLMaterial;
typedef struct _RLObject*		RLPath;
typedef struct _RLObject*		RLShadow;
typedef struct _RLObject*		RLAnimation;
typedef struct _RLObject*		RLAnimationSet;
typedef unsigned long			RLColour;
typedef char*				RLAttribute;

#ifdef FIXED_POINT_API
typedef long int	RLValue;
#ifndef __psx__
#define RLVal(x)		((RLValue)((x) * (double)(1<<16)))
#else
#define RLVal(x)		((RLValue)((x) * 65536))
#endif
#define RLInt(x)		((x) >> 16)
#define RLFloat(x)		((x) / 65536.0)
RLValue RLDivide(RLValue, RLValue);
RLValue RLMultiply(RLValue, RLValue);
#define RLMultiply3(a,b,c)	RLMultiply(RLMultiply(a, b), c)
#else
typedef float 		RLValue;
#define RLVal(x)	((RLValue) (x))
#define RLInt(x)	((int)(x))
#define RLFloat(x)	((float) (x))
#define RLDivide(a,b)	((RLValue) ((double) (a) / (double) (b)))
#define RLMultiply(a,b)	((RLValue) ((a) * (b)))
#define RLMultiply3(a,b,c)	((RLValue) ((a) * (b) * (c)))
#endif

/*
 * Error codes
 */

typedef enum _RLError {
    RLNoError = 0,		/* no error */
    RLBadObject,		/* object expected in argument */
    RLBadType,			/* bad argument type passed */
    RLBadAlloc,			/* out of memory */
    RLFaceUsed,			/* face already used in a mesh */
    RLNotFound,			/* object not found in specified place */
    RLNotDoneYet,		/* unimplemented */
    RLFileNotFound,		/* file cannot be opened */
    RLBadFile,			/* data file is corrupt */
    RLBadDevice,		/* device is not compatible with renderer */
    RLBadValue,			/* bad argument value */
    RLBadMajorVersion,		/* bad dll major version */
    RLBadMinorVersion,		/* bad dll minor version */
    RLMaxError
} RLError;

typedef void (*RLErrorHandler)
    (RLError error,		/* error which was generated */
     void* arg			/* argument given to RLAddErrorHandler */
     );

typedef void (*RLDestroyCallback)
    (RLObject obj,		/* object being destroyed */
     void* arg			/* argument given to RLAddDestroyCallback */
     );

typedef void (*RLFrameCallback)
    (RLFrame frame,		/* frame being moved */
     void* arg			/* argument given to RLAddFrameCallback */
     );

typedef RLTexture (*RLTextureNameCallback)
    (char* tex_name,		/* texture name to be loaded.	*/
    void* arg			/* argument given to RLLoadMeshWithTextures. */
    );
    
typedef struct _RLVector {
    RLValue x, y, z;
} RLVector;

typedef struct _RLQuaternion {
    RLValue s;
    RLVector v;
} RLQuaternion;

typedef struct _RLVector4d {
    RLValue x, y, z, w;
} RLVector4d;

typedef RLValue RLMatrix4d[4][4];

typedef struct _RLBox {
    RLVector min, max;
} RLBox;

typedef void (*RLWrapCallback)(RLVector*, int* u, int* v,
			       RLVector* a, RLVector* b, void*);
typedef enum _RLLightType {
    RLLightAmbient,
    RLLightPoint,
    RLLightSpot,
    RLLightDirectional,
    RLLightParallelPoint
} RLLightType;

typedef enum _RLRenderQuality {
    RLRenderWireframe,		/* display just the edges */
    RLRenderUnlitFlat,		/* flat shaded without lighting */
    RLRenderFlat,		/* flat shaded */
    RLRenderGouraud,		/* gouraud shaded */
    RLRenderPhong		/* phong shaded */
} RLRenderQuality;

typedef enum _RLLightingFrequency {
    RLLightNever,
    RLLightOnce,
    RLLightContinually
} RLLightingFrequency;

typedef enum _RLTextureQuality {
    RLTextureNearest,		/* choose nearest pixel in texture */
    RLTextureLinear		/* linearly interpolate 4 nearest pixels */
} RLTextureQuality;

typedef enum _RLCombineType {
    RLCombineReplace,
    RLCombineBefore,
    RLCombineAfter
} RLCombineType;

typedef enum _RLColourModel {
    RLColourRamp, RLColourRGB
} RLColourModel;

typedef enum _RLPaletteFlags {
    RLPaletteFree,		/* renderer may use this entry freely */
    RLPaletteReadOnly,		/* fixed but may be used by renderer */
    RLPaletteReserved		/* may not be used by renderer */
} RLPaletteFlags;

typedef struct _RLPaletteEntry {
    unsigned char red;		/* 0 .. 255 */
    unsigned char green;	/* 0 .. 255 */
    unsigned char blue;		/* 0 .. 255 */
    unsigned char flags;	/* one of RLPaletteFlags */
} RLPaletteEntry;

typedef void (*RLRenderCallback)
    (RLDevice dev,		/* device being rendered */
     void* arg,			/* render_arg passed XXX RLCreateMemoryDevice */
     void* buffer1,		/* buffer being updated */
     void* buffer2,		/* second buffer (if doublebuffering) */
     int x1, int y1,		/* top left of updated rectangle */
     int x2, int y2		/* bottom left of updated rectangle
				 * (non-inclusive) */
     );

typedef void (*RLPaletteCallback)
    (RLDevice dev,		/* device being changed */
     void* arg,			/* palette_arg in XXX RLMemoryDeviceInfo */
     int pixel,			/* pixel number being changed */
     int red,			/* red component (0 .. 255) */
     int green,			/* green component (0 .. 255) */
     int blue			/* blue component (0 .. 255) */
     );
typedef void (*RLObjectEnumerateCallback)
    (RLObject id,		/* the object */
     char* object_type,		/* a string describing the object type */
     void* arg			/* arg passed to RLEnumerateObjects */
     );

typedef struct _RLImage {
    int width, height;		/* width and height in pixels */
    int aspectx, aspecty;	/* aspect ratio for non-square pixels */
    int depth;			/* bits per pixel */
    int rgb;			/* if false, pixels are indices into a
				   palette otherwise, pixels encode
				   RGB values. */
    int bytes_per_line;		/* number of bytes of memory for a
				   scanline. This must be a multiple
				   of 4. */
    void* buffer1;		/* memory to render into (first buffer). */
    void* buffer2;		/* second rendering buffer for double
				   buffering, set to NULL for single
				   buffering. */
    unsigned long red_mask;
    unsigned long green_mask;
    unsigned long blue_mask;
    unsigned long alpha_mask;
    				/* if rgb is true, these are masks for
				   the red, green and blue parts of a
				   pixel.  Otherwise, these are masks
				   for the significant bits of the
				   red, green and blue elements in the
				   palette.  For instance, most SVGA
				   displays use 64 intensities of red,
				   green and blue, so the masks should
				   all be set to 0xfc. */
    int palette_size;           /* number of entries in palette */
    RLPaletteEntry* palette;	/* description of the palette (only if
				   rgb is false).  Must be (1<<depth)
				   elements. */
} RLImage;

typedef enum _RLEventType {
    RLEventButtonPress, RLEventButtonRelease,
    RLEventKeyPress, RLEventKeyRelease,
    RLEventDrag
} RLEventType;

typedef struct _RLEvent {
    RLEventType		type;
    int			x, y;
    union {
	int		button;
	int		key;
    } u;
} RLEvent;

/*
 * Get the code for the last error generated by the system.
 */
RLError			RLGetLastError(void);

/*
 * Generate an error, calling all error handlers and returning the error
 * which was raised.
 */
RLError			RLRaiseError(RLError error);

/*
 * Register a function to be called when a runtime error is detected.
 * It is always safe for an error handler to return; the system will
 * recover from the error appropriately.
 */
RLError			RLAddErrorHandler(RLErrorHandler fn,
					  void* arg);

/*
 * Remove an error handler previously registered with
 * RLAddErrorHandler.
 */
RLError			RLRemoveErrorHandler(RLErrorHandler fn,
					     void* arg);

/*
 * Add elements to the current file search path.
 */
RLError                 RLAddSearchPath(const char* path);

/*
 * Set the current file search path.  To clear the search path,
 * pass NULL.
 */
RLError                 RLSetSearchPath(const char* path);

/*
 * Get the current file search path.  The number of elements in the path
 * is returned in *count_return and an array of strings, one for each
 * element in the path is returned in *path_return.  The application must
 * free each of these strings along with the array itself.
 */
RLError                 RLGetSearchPath(int* count_return,
                                        char*** path_return);

/*
 * Return a descriptive string for an error.
 */
const char*		RLErrorString(RLError error);

/* 
 * Destroy an object.  The object will only be actually destroyed if
 * it is not used by any other object.
 */
RLError			RLObjectDestroy(RLObject object);

/*
 * Duplicate an object.
 */ 
RLObject		RLObjectCopy(RLObject object);

/*
 * Set the object's name.
 */
RLError			RLObjectSetName(RLObject object, const char* name);

/*
 * Get the object's name.
 */
const char*		RLObjectGetName(RLObject object);

/*
 * Find an object given its name.  Returns NULL if no object found.
 */
RLObject		RLObjectFromName(const char* name);

/*
 * Determine whether an object exists (i.e. it has not been destroyed
 * using RLObjectDestroy or via normal system reference countine).
 * Returns RLNoError if the object exists or RLBadObject if not.  No
 * error will be generated and the application's error handlers will
 * not be called.
 */
RLError			RLObjectExists(RLObject object);

/*
 * Return the name of the object's class.  Returns NULL on error.
 */
const char*		RLObjectGetClassName(RLObject object);

/*
 * Inform the system that the application is holding a long-term
 * reference to an object.  This can be used to prevent the system
 * from automatically reclaiming the memory for a texture when the
 * meshes which use it are destroyed or a commonly used mesh when it
 * is removed from its frame.
 */
RLError			RLObjectReference(RLObject object);

/*
 * this function returns the total number of references to the
 * given object that exist due to both the system, and the
 * RLObjectReference call. If the object doesn't exist the
 * returned value will be 0
 */
long 			RLObjectGetReferenceCount(RLObject object);

/*
 * Register a function to be called when an object is destroyed.
 */
RLError			RLObjectAddDestroyCallback(RLObject object,
						   RLDestroyCallback fn,
						   void* arg);
/*
 * Remove a function previously registered with RLObjectAddDestroyCallback.
 */
RLError			RLObjectRemoveDestroyCallback(RLObject object,
						      RLDestroyCallback fn,
						      void* arg);

RLError 		RLObjectGetDestroyCallbacks(RLObject object,
				   		    int* count,
				   		    RLDestroyCallback **fns,
				   		    void* **args);

/*
 * Duplicate an object.  This manufactures a separate copy of the
 * given object, including its attributes.
 */ 
RLObject		RLObjectCopy(RLObject object);

/*
 * Set the application data for an object.
 */
RLError			RLObjectSetAppData(RLObject object,
					   unsigned long data);

/*
 * Get the application data for an object.
 */
unsigned long		RLObjectGetAppData(RLObject object);

/*
 * Create a wrapping function which can be used to assign texture
 * coordinates to faces and meshes.
 */

typedef enum _RLWrapType {
    RLWrapFlat,
    RLWrapCylinder,
    RLWrapSphere,
    RLWrapChrome
} RLWrapType;

RLWrap			RLCreateWrap(RLWrapType type,
				     RLFrame refid,
				     RLValue ox, RLValue oy, RLValue oz,
				     RLValue dx, RLValue dy, RLValue dz,
				     RLValue ux, RLValue uy, RLValue uz,
				     RLValue ou, RLValue ov,
				     RLValue su, RLValue sv);

/*
 * Apply the wrap to the vertices of the object.
 */
RLError			RLWrapApply(RLWrap, RLObject);

/*
 * Apply the wrap to the vertices of the object, first transforming each
 * vertex by the frame's world transform and the wrap's reference frame's
 * inverse world transform.  Generate an RLBadValue error if the wrap
 * does not have a reference frame.
 */
RLError			RLWrapApplyRelative(RLWrap, RLFrame frame, RLObject);

/* 
 * Create a device for rendering the the screen or window.  Note that
 * the device which is created may have different width and height
 * than those passed to RLCreateDevice.  Use RLDeviceGetWidth and
 * RLDeviceGetHeight to find the correct values.
 */
RLDevice		RLCreateDevice(int width, int height);

/*
 * Create a device for rendering to offscreen memory.
 */
RLDevice		RLCreateMemoryDevice(RLImage* image,
					     RLImage* zimage,
					     RLRenderCallback render,
					     void* render_arg,
					     RLPaletteCallback set_colour,
					     void* set_colour_arg);

/*
 * Return a list of devices in *devices_return and *count_return.
 */
RLError			RLGetDevices(int* count_return,
				     RLDevice** devices_return);

RLError			RLDeviceUpdate(RLDevice dev);

/*
 * Use to lock against VSync on a given device
 */
RLError			RLDeviceSync(RLDevice);

/*
 * Return a list of the viewports on a device in *views_return and
 * *count_return.
 */
RLError			RLDeviceGetViewports(RLDevice dev,
					     int* count_return,
					     RLViewport** views_return);

/*
 * Return the width in pixels of a Device.
 */
int			RLDeviceGetWidth(RLDevice);

/*
 * Return the height in pixels of a Device.
 */
int			RLDeviceGetHeight(RLDevice);

/*
 * Return the number of polygons rendered since the device was created.
 */
long			RLDeviceGetPolygonsDrawn(RLDevice);

/*
 * Set the dither flag for the device.  Default is TRUE.
 */
RLError			RLDeviceSetDither(RLDevice, int);

/*
 * Get the dither flag for the device.  Returns -1 on error.
 */
int			RLDeviceGetDither(RLDevice);


/*
 * Get the palette and palette flags for an 8 bit device.
 * Note palette_return must be freed with RLFree.
 */
RLError			RLDeviceGetPalette(RLDevice id,
					   int start, int size,
					   RLPaletteEntry** palette_return);

/*
 * Set the palette and palette flags for an 8 bit device.
 */
RLError			RLDeviceSetPalette(RLDevice id,
					   int start, int size,
					   RLPaletteEntry* palette);

/*
 * Set the rendering quality for the device.  Default is RLRenderFlat.
 */
RLError			RLDeviceSetQuality(RLDevice, RLRenderQuality);

/*
 * Get the rendering quality for the device.  Returns -1 on error.
 */
RLRenderQuality		RLDeviceGetQuality(RLDevice);

/*
 * Get the preferred Image format for the current device, need to call
 * RLFree on the returned RLImage
 */
RLError RLDeviceGetImageFormat(RLDevice, RLImage**);

/*
 * Set options for rendering wireframe objects.  The options argument is
 * a bitmask of the following bits.  The default value is
 * (RLWireframeCull|RLWireframeHiddenLine).
 */

#define RLWireframeCull		1 /* cull backfaces */
#define RLWireframeHiddenLine	2 /* lines are obscured by closer objects */

RLError			RLDeviceSetWireframeOptions(RLDevice, int options);

/*