03.03.19 - Version 1.1 - XGLv6 now includes the VRML CCW shape field (XGL_SHAPE_CCW_TOKEN), a new token (XGL_TEXTURE_INDICES_TOKEN) that defines the texture indices, and a modification of the data following an XGL_SHAPE to support additional VRML.

toc

XGL Specification (IXGL.h)

#ifndef _I_XGL_H_
#define	_I_XGL_H_


/**
 * IXGL - interface defining the [X]Plane/e[X]tensible [G]raphics [L]anguage
 * 
 * This is a "work in progress" and will be growing as we add support for
 * additional primitivies, tokens, etc., etc.
 * 
 * Unless othewise specified, each of the IDs/tokens/commands begining with XGL_
 * are followed by data as document with the token.
 * 
 * VERY IMPORTANT NOTE:
 * ====================
 * Beginning with XGLv5, we have implemented a new strategy for XGL that will
 * make it much, much easier for parsers, and for us to add new tokens
 * without changing the XGL version again (hopefully!)
 * 
 * ALL TOKENS are immediately followed by an INTEGER bytecount containing
 * the number of bytes encapsulated by that token (0 if there is no data associated
 * with the token).
 * 
 * This ALSO applies to ALL tokens that are "inside" other tokens, such as XGL_SHAPE,
 * MATERIAL, and most others that contain tokens to represent their data (XGL_FLOAT_ARRAY,
 * XGL_INT_ARRAY, XGL_CHARS_ARRAY). 
 * 
 * SUMMARY: When you read an integer token, ALWAYS read an integer bytecount after
 * the token.  If you do not care about or handle that token, simply SKIP the
 * number of bytes.
 * 
 * @author dspotts
 */

	///////////////////////////////////////////////////////////////////////////
	/*
	 * Current XGL Version - NOT a token!
	 * 
	 * @since v2
	 */
	const int XGL_CURRENT_VERSION_VALUE = 5;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * Format token
	 * 
	 * ALWAYS the FIRST token in an XGL stream so that
	 * applications can easily tell if the stream is XGL.
	 * 
	 * No data follows
	 * 
	 * @since v2
	 */
	const int XGL_FORMAT_TOKEN = 0x5858474C; // 'XXGL'
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * Version token
	 * 
	 * Always the SECOND token in an XGL stream/file followed by an integer
	 * defining the version of the data.
	 * 
	 * @since v2
	 */
	const int XGL_VERSION_TOKEN = 0xffff;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * Float array token
	 * 
	 * An array of floats, preceded by an integer count
	 * 
	 * @since v1
	 */
	const int XGL_FLOAT_ARRAY = 0x0000;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * Integer array token
	 * 
	 * An array of ints, preceded by an integer count
	 * 
	 * @since v1
	 */
	const int XGL_INT_ARRAY = 0x0001;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * CHARS token
	 * 
	 * Followed by an integer indicating the number of characters, and
	 * the characters themselves (individual byte for each char, not unicode).
	 * 
	 * @since v4
	 * 
	 */
	const int XGL_CHARS_ARRAY = 0x0013;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * Reset material command, all shapes should be preceded by this command, which
	 * is used to reset the materials back to default values
	 * 
	 * @since v1
	 */
	const int XGL_RESET_MATERIAL = 0x0003;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * OpenGL Material token
	 * 
	 * This command is followed by an integer material type ID, such as
	 * GL_DIFUSE, etc., then a 3 element XGL_FLOAT_ARRAY representing the RGB values
	 * for this material.
	 * 
	 * Material commands should be issued prior to geometry commands.
	 * 
	 * @since v1
	 */
	const int XGL_MATERIAL = 0x0004;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * A token similar to a VRML shape object.
	 * 
	 * We currently only support the geometry of a shape in a very compact form,
	 * similar to VRML.
	 * 
	 * VRML generally begins with a "global" vertex list (3 floats per vertex),
	 * and we currently represent a shape by including this global point list
	 * within the FIRST shape object within an XGL file.
	 * 
	 * So the first shape command is followed by an XGL_FLOAT_ARRAY, then that
	 * shape's indices using an XGL_INT_ARRAY.
	 * 
	 * Subsequent shapes avoid duplicating the point array, and are followed
	 * ONLY by a single XGL_INT_ARRAY defining the indices for this shape's
	 * vertices.
	 * 
	 * Like VRML, the index list is a list of integers that index into the float
	 * array (3*index = [x][y][z]) to define a vertex.
	 * 
	 * Like VRML, this is one large list of indexes, with "-1" indicating the end
	 * of a polygon and separating each polygon.
	 * 
	 * Examples:
	 * =========
	 * 
	 * 0, 1, 2, -1 ==> a triangle with vertices 0, 1, 2
	 * 
	 * 0, 1, 2, -1, 0, 1, 2, 3, -1 ==> triangle and a quad
	 * 
	 * @since v1
	 */
	const int XGL_SHAPE = 0x0005;
	///////////////////////////////////////////////////////////////////////////


	///////////////////////////////////////////////////////////////////////////
	/*
	 * Bounding box of the XGL object
	 * 
	 * The bounding box defines the outside dimensions of the object contained 
	 * within an XGL file.  This is especially handy for viewers/renderers, and
	 * may have additional benefits.
	 * 
	 * These dimensions only define the SIZE of the object: width, height, depth
	 * (zero-based, always positive).
	 * 
	 * Followed by  an XGL_FLOAT_ARRAY of 3 floats (x, y, z)
	 */
	const int XGL_BOUNDING_BOX = 0x0006;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * Texture File token
	 * 
	 * Defines all texture files used within an XGL object.  A single
	 * XGL_TEXTURE_FILE_TOKEN will be at the start of the file for easy/fast
	 * finding and loading, texture prioritization, etc.
	 * 
	 * This token is followed by an integer count of the number of unique
	 * texture files.
	 * 
	 * Following this are multiple XGL_CHAR_ARRAY objects, one for each texture
	 * name.
	 * 
	 * The files are placed in XGL in the order that is consistent with the
	 * XGL_TEXTURE_INDEX token.
	 * 
	 */
	const int XGL_TEXTURE_FILE_TOKEN = 0x0007;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * Texture to bind to
	 * 
	 * This is be a zero-based index from the textures associated with this
	 * XGL file.  It will be up to the application to convert this to a "real"
	 * OpenGL texture index.
	 * 
	 * This token will be followed by an integer, and *always* preceed any shape
	 * that uses textures.
	 * 
	 * @since v3
	 * 
	 */
	const int XGL_TEXTURE_INDEX = 0x0008;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * Texture floats (S and T) parameters.
	 * 
	 * For any shape that has a texture associated with it, that shape will be
	 * preceded by XGL_TEXTURE_FLOATS.
	 * 
	 * The number of floats will be 2* the number of vertices in the upcoming
	 * shape, and be represented by an XGL_FLOAT_ARRAY.
	 * 
	 * @since v3
	 * 
	 */
	const int XGL_TEXTURE_FLOATS = 0x0009;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * End of stream token
	 * 
	 * This token signifies the end of an XGL stream.
	 * 
	 * @since v4
	 * 
	 */
	const int XGL_END_OF_STREAM = 0x0010;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * OPTIONAL shape HINT token
	 * 
	 * This token, which, if present, precedes an XGL_SHAPE, is followed by
	 * an integer that can be used to signify any "special" information regarding 
	 * the upcoming shape object.
	 * 
	 * Please see http://www.dspotts.com/xgl.html for details on this token as
	 * well as the modeler's guidelines for texture naming so that these
	 * tokens can be added to the XGL file(s).
	 *  
	 * @since v4
	 * 
	 */
	const int XGL_SHAPE_HINT_TOKEN = 0x0011;
	///////////////////////////////////////////////////////////////////////////

	///////////////////////////////////////////////////////////////////////////
	/*
	 * OPTIONAL shape hint DATA token
	 * 
	 * If a particular shape hint requires more data than a single integer,
	 * it can be followed by this token.
	 * 
	 * @since v4
	 * 
	 */
	const int XGL_SHAPE_HINT_DATA_TOKEN = 0x0012;
	///////////////////////////////////////////////////////////////////////////


	///////////////////////////////////////////////////////////////////////////
	/*
	 * Number of bytes of various data types used in XGL
	 */
	const int SIZEOF_INT = 4;
	const int SIZEOF_FLOAT = 4;
	const int SIZEOF_TOKEN = 4;
	const int SIZEOF_BYTE = 1;
	///////////////////////////////////////////////////////////////////////////
	
/*
 * OpenGL constants for material specifications
 */
#ifndef GL_AMBIENT 
const int GL_AMBIENT = 0x1200;
const int GL_DIFFUSE = 0x1201;
const int GL_SHININESS = 0x1601;
const int GL_EMISSION = 0x1600;
const int GL_SPECULAR = 0x1202;
#endif


#endif

XPXGL Extensions

The following constants define the various XPXGL shape hint data values (an integer) - note from the above handle hint code that for light(s), the rgb values are stored in the upper 3 bytes of the data (NN, NN, NN) and must be masked off for these 2 tokens.

///////////////////////////////////////////////////////////////////////////
/*
 * Current XGL_SHAPE_HINT_TOKEN values
 */
const int XPXGL_SHAPE_HARD = 0x0001;
const int XPXGL_SHAPE_LIGHT = 0x0002;
const int XPXGL_SHAPE_LIGHT_BLINK = 0x0003;
const int XPXGL_SHAPE_SMOKE1 = 0x0004;
const int XPXGL_SHAPE_SMOKE2 = 0x0005;

///////////////////////////////////////////////////////////////////////////