Plush v1.1 API Documentation

Preface

Welcome to the Plush v1.1 API Documentation. This doc serves totally as a reference. For examples and a tutorial, please see [whatever].

Some Notes

Definitions

These are #defines that can be found in pl_defs.h and pl_conf.h:



Name	Value/Meaning
PL_PI	3.14159265359
PL_SHADE_*	Shade types for use with pl_Mat.ShadeType. PL_SHADE_NONE: no shading PL_SHADE_FLAT: flat light shading. If no lights, behaves just like PL_SHADE_NONE PL_SHADE_FLAT_DISTANCE: flat distance shading. Note: this can be bitwise ORed (i.e. |) with PL_SHADE_FLAT for both. PL_SHADE_GOURAUD: Gouraud light shading. PL_SHADE_GOURAUD_DISTANCE: Gouraud distance shading. Note: this can be bitwise ORed (i.e. |) with PL_SHADE_GOURAUD for both.
PL_LIGHT_*	Light Modes for use with plLightSet() and pl_Light.Type. PL_LIGHT_NONE: no light (why would you use this?) PL_LIGHT_VECTOR: vector light at an infinite distance. PL_LIGHT_POINT_DISTANCE: point proximity light. The closer an object is to this the brighter it is. PL_LIGHT_POINT_ANGLE: point light, with intensity calculated by angle between light->object vector and normal of object. PL_LIGHT_POINT: a combination of the previous two.
PL_MAX_CHILDREN	The maximum number of children a pl_Obj can have. (Typically 16)

Types

Plush has a number of different types that you might need to use in your programs. They are all defined in pl_conf.h (simple types) pl_types.h (complicated structure types). Here they are:



Simple Types
Name	Definition
pl_ZBuffer	The Z-buffer type. Usually used when allocating a zbuffer, usually float.
pl_Float	General floating point type, usually float or double
pl_IEEEFloat32	32 bit IEEE floating point, usually float or double. Only really used with .3DS reader
pl_sInt32	Signed 32 bit integer, usually signed long int
pl_uInt32	Unsigned 32 bit integer, usually unsigned long int
pl_sInt16	Signed 16 bit integer, usually signed short int
pl_uInt16	Unsigned 16 bit integer, usually unsigned short int
pl_sInt	Signed optimal integer, usually signed int
pl_uInt	Unsigned optimal bit integer, usually unsigned int
pl_Bool	Fake boolean value. Usually char.
pl_uChar	Unsigned 8 bit type, usually unsigned char
pl_sChar	Signed 8 bit type, usually signed char





Non-Simple Types
Name	Definition
pl_Cam	Camera type. See plCamera*(). Contents: pl_Float Fov: Field of view in degrees. Should be between 1 and 179 pl_Float Aspect ratio: Aspect ratio, normally 1.0, but in wierd resolutions, this should be something like "screenwidth/screenheight * 3.0/4.0." pl_sChar Sort: How shall plRender*() sort polygons? 0: no sorting. -1: front to back. 1: back to front. pl_Float ClipBack: sets the far clip plane. Any value less than or equal to 0.0 disables the far clip plane. pl_sInt ClipTop, ClipLeft, ClipBottom, ClipRight: screen clipping coords. Usually 0, 0, screenheight, screenwidth respectively. pl_uintScreenWidth, ScreenHeight: the screen width (line width) and screen height of the framebuffer. pl_sInt CenterX, CenterY: the place on the screen where 0,0,z projects to. Usually screenwidth/2 and screenheight/2 respectively. pl_Float X, Y, Z: The X Y and Z coordinates of the Camera in Worldspace. pl_Float Pitch, Pan, Roll: The rotation of the Camera in Worldpsace. Pitch is the up-down rotation, with positive being up. Pan is left-right rotation, with positive being right, and Roll is rotation around the viewing axis, with positive being clockwise. pl_uChar * frameBuffer: a pointer to the buffer of type pl_uChar, and dimensions screenwidth*screenheight to which rendering will occur. pl_ZBuffer * zBuffer: a pointer to the buffer of type pl_ZBuffer, and dimensions screenwidth*screenheight to which Z-buffering will occur. Or NULL, to disable Z-buffering.
pl_Light	Light type. See plLight*(). Contents: pl_uChar Type: Type of light, one of PL_LIGHT_* pl_Float Xp, Yp, Zp: This can mean two things: If Type is PL_LIGHT_VECTOR: the unit vector of the light If Type is PL_LIGHT_POINT_*: the position of the light pl_Float Intensity: The intensity of the light. Usually from 0.0 to 1.0. Can be greater and brightness will be clipped. pl_Float HalfDistSquared: The square of the distance at which PL_LIGHT_POINT or PL_LIGHT_POINT_DISTANCE will be 1/2 brightness.
pl_Obj	Object type. See plObj*(). Contents: pl_uInt32 NumVertices: the number of vertices in the object. pl_uInt32 NumFaces: the number of faces (triangles) in the object. pl_Vertex * Vertices: a pointer to an array of "NumVertices" vertices. pl_Face * Faces: a pointer to an array of "NumFaces" faces. pl_Obj Children[ PL_MAX_CHILDREN]: a list of children. Either pointers to the children, or 0 if no children. pl_Bool BackfaceCull: are backfacing triangles drawn in this object? pl_Bool BackfaceIllumination: are triangles illuminated from lights that are behind them? pl_Bool GenMatrix: generate a transformation matrix from the following? pl_Float Xp, Yp, Zp, Xa, Ya, Za: Translation and Rotation values. Translation values are in object space. Rotation values are in degrees. Rotations happen around the X then Y then Z. These are only used if GenMatrix is set (see above) pl_Float Matrix[16]: A 4x4 transformation matrix which is used if GenMatrix is not set. pl_Float RotMatrix[16]: A 4x4 transformation matrix for normals (i.e. no translation) which is used if GenMatrix is not set.
pl_Vertex	Vertex type. Used with pl_Obj. Contents: pl_Float x, y, z: the WorldSpace coordinates of the point. pl_Float xformedx, xformedy, xformedz: the transformed coordinates of the point. pl_Float nx, ny, nz: the WorldSpace normal of the point. pl_Float xformednx, xformedny, xformednz: the transformed normal of the point.
pl_Face	Face (triangle) type. Used with pl_Obj. Contents: pl_Vertex *Vertices[3]: pointers to the three vertices of the triangle. pl_Float nx, ny, nz: the normal of the triangle in object space. pl_Mat *Material: the material of the face. pl_sInt32 Scrx[3], Scry[3]: the projected screen coordinates of the vertices, in 16.16 fixed point. pl_Float Scrz[3]: the reciprocal of the transformed Z of the vertices. pl_sInt32 MappingU[3], MappingV[3]: the 16.16 fixed point mapping coordinates of the face pl_sInt32 eMappingU[3], eMappingV[3]: the 16.16 fixed point environment mapping coordinates of the face (generated on the fly) pl_Float fShade: the shade of the face (for flat shading), 0.0->1.0 pl_Float sLighting: the static lighting value for flat shading, usually 0.0 pl_Float Shades[3]: the shades of the vertices (for Gouraud shading), 0.0->1.0 pl_Float vsLighting[3]: the static lighting values for Gouraud shading, usually 0.0
pl_Mat	Material Type. Used with pl_Face. See plMat*() Contents: pl_sInt Ambient[3]: RGB of surface color (0-255 is a good range) pl_sInt Diffuse[3]: RGB of diffuse reflection (0-255 is a good range) pl_sInt Specular[3]: RGB of "specular" highlights (0-255 is a good range) pl_uInt Shininess: Shininess of material. 1 is dullest, 2 is shinier, etc. pl_Float FadeDist: For distance shading, distance at which intensity is 0 pl_uChar ShadeType: Shade type: PL_SHADE_* pl_uChar Transparent: Transparency index (0 = none, 4 = alot) Note: transparencies disable textures pl_uChar PerspectiveCorrect: Correct textures every n pixels. Will be rounded down to the nearest power of two. i.e. 20 will become 16. Values over 64 will become 64. pl_Texture *Texture: Texture map, or NULL if none. pl_Texture *Environment: Environment map, or NULL if none. Note: if both Texture and Environment are set, shading will be disabled. pl_Float TexScaling: Texture map scaling (usually 1.0) pl_Float EnvScaling: Environment map scaling (usually 1.0) pl_Bool zBufferable: Can this material be zbuffered? Usually true. pl_uInt NumGradients: Desired number of gradients to be used _*: Internal variables (see pl_types.h for more info)
pl_Texture	Texture Type. Used with pl_Mat. See plTex*(). Contents: pl_uChar *Data: the texture data, one byte per pixel. pl_uChar *PaletteData: the palette data, 256 RGB triplets. Each value should be 0-255. pl_uChar Width, Height: the log2 of dimensions. i.e. 8, 8 for a 256x256 texture. pl_uInt iWidth, iHeight: the actual dimensions. i.e. 256,256 for a 256x256 texture. pl_Float uScale, vScale: the texture scaling, usually 1.0, 1.0 pl_uInt NumColors: the number of colors used in the texture.
pl_Spline	Spline Type. See plSpline*(). Contents: pl_Float *keys: the key data, keyWidth*numKeys plFloats. pl_sInt keyWidth: number of pl_Floats per key. pl_sInt numKeys: number of keys in spline pl_Float cont: The continuity of the spline. Should be between -1.0 and 1.0. pl_Float bias: The bias of the spline. Should be between -1.0 and 1.0. pl_Float tens: The tension of the spline. Should be between -1.0 and 1.0.