bsp.h

Go to the documentation of this file.

/*
 * bsp.h
 *
 * Copyright (C) 2010  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Logical parsing of Quake BSP format streams.
 */

#ifndef WAVEPACKET_QUAKE_BSP_H__
#define WAVEPACKET_QUAKE_BSP_H__

// includes --------------------------------------------------------------------
#include "bsp-version.h"

#include "nstream/nstream.h"


namespace quake {

////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup quake
/// \defgroup quake_bsp Quake BSP Parsing Library
///
/// This is a simple library for parsing Quake's BSP file format.
///
/// A BSP file contains a 3D map (BSP stands for Binary Space Partitioning).
/// Typically the file contains several "lumps", and each lump contains a list
/// of objects.  Example lumps are textures, polygons, vertices, map entities,
/// effects, etc.
///
/// <b>How to use this parsing library:</b>  The library is designed to handle
/// a wide range of BSP formats.  In general, different vendors (game companies)
/// have slightly different BSP formats.  They'll use different lumps, and maybe
/// even have slightly different objects in lumps with the same name.
///
/// This library will attempt to determine the vendor that created the BSP
/// based on the BSP header, then allow the caller to iterate over available
/// lumps, and likewise iterate over objects in each lump.  You should write
/// your code to expect some common lumps always (nodes, faces, textures, ...)
/// but treat other vendor-specific lumps as optional.  The more flexible you
/// are, the more likely it is you can handle BSP files from multiple vendors.
///
/// <b>Warning:</b> do not use the objects defined here (texture_t, face_t,
/// etc.) in your rendering code.  These objects are defined for convenience
/// and safety in parsing, not high-speed rendering.  For instance, they have
/// a high per-object overhead due to vtables.  Just use these objects for
/// parsing, and have your own simple structs to store thousands of vertices,
/// for instance.
///
/// See these links for references on the BSP format:
///  - http://www.mralligator.com/q3/
///  - http://developer.valvesoftware.com/wiki/The_Source_Engine_BSP_File_Format
///  - http://www.paulsprojects.net/opengl/q3bsp/q3bsp.html
///  - http://en.wikipedia.org/wiki/BSP_(file_format)
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/



/// an object in a lump.  This is a base class from which the actual object
/// structures are subclassed.
struct lump_object_t {
        // virtual destructor --------------------------------------------------
        virtual ~lump_object_t(void) throw();

        // quake::lump_object_t struct interface methods -----------------------

        /// what sort of lump object is this really?  Can use this information
        ///     to perform a dynamic cast to the correct leaf class.
        virtual eLumpType getType(void) const throw() { return eLump_Invalid; }

        /// returns the index of this object as stored in its lump
        virtual int getIndex(void) const throw() { return index; }

        // data fields
        int             index;
};



/// polygon face type
enum eFaceType {
        eFace_Polygon           =  1, ///< standard polygon using vertices
        eFace_Patch             =  2, ///< bezier patches
        eFace_Mesh              =  3, ///< triangle mesh using meshverts
        eFace_Billboard         =  4, ///< 2D billboard, location only

        // keep this last!
        eFace_Invalid           =  0
};



/// a game entity in the bsp map
struct entity_t : public lump_object_t {
        ~entity_t(void) throw();
        eLumpType getType(void) const throw() { return eLump_Entities; }

        // data fields
        Dictionary      dictionary;     ///< key/value pairs
};



/// a polygon face in the bsp map
struct face_t : public lump_object_t {
        ~face_t(void) throw();
        eLumpType getType(void) const throw() { return eLump_Faces; }

        // data fields
        int32_t         texture;        ///< index to texture path object
        int32_t         effect;         ///< index to effect (or -1)
        int32_t         type;           ///< face type (eFaceType, above)
        int32_t         vertex;         ///< index of first vertex
        int32_t         nVertices;      ///< number of vertices
        int32_t         meshvert;       ///< index of first mesh vertex
        int32_t         nMeshverts;     ///< number of mesh vertices
        int32_t         lmIndex;        ///< light map index
        int32_t         lmStart[2];     ///< corner of this face's lightmap
        int32_t         lmSize[2];      ///< size of this face's lightmap
        point3d_t       origin;         ///< origin of lightmap
        point3d_t       lmVecs[2];      ///< lightmap s and t vectors
        point3d_t       normal;         ///< surface normal
        int32_t         size[2];        ///< patch dimensions
};



/// a node in the BSP tree
///  Note that the indexing scheme is unusual:
///   - A non-negative index refers to a node
///   - A negative index is a leaf, -(leaf + 1)
struct node_t : public lump_object_t {
        ~node_t(void) throw();
        eLumpType getType(void) const throw() { return eLump_Nodes; }

        // data fields
        int32_t         plane;          ///< index to plane
        int32_t         children[2];    ///< left, right child
        int32_t         min[3];         ///< bounding box min xyz coords
        int32_t         max[3];         ///< bounding box max xyz coords
};



/// a leaf in the BSP tree
struct leaf_t : public lump_object_t {
        ~leaf_t(void) throw();
        eLumpType getType(void) const throw() { return eLump_Leafs; }

        // data fields
        int32_t         cluster;        ///< cluster index
        int32_t         area;           ///< map area (for portals?)
        int32_t         min[3];         ///< bounding box min xyz coords
        int32_t         max[3];         ///< bounding box max xyz coords
        int32_t         leafface;       ///< first leaf face for leaf
        int32_t         n_leaffaces;    ///< number of faces
        int32_t         leafbrush;      ///< first leaf brush for leaf
        int32_t         n_leafbrushes;  ///< number of brushes
};



/// a leaf face in the BSP tree
struct leafface_t : public lump_object_t {
        ~leafface_t(void) throw();
        eLumpType getType(void) const throw() { return eLump_Leaffaces; }

        // data fields
        int32_t         face;           ///< face index
};



/// a mesh vertex
struct meshvert_t : public lump_object_t {
        ~meshvert_t(void) throw();
        eLumpType getType(void) const throw() { return eLump_Meshverts; }

        // data fields
        int32_t         vertex;         ///< vertex index
};



/// a 2D plane in the BSP tree
struct plane_t : public lump_object_t {
        ~plane_t(void) throw();
        eLumpType getType(void) const throw() { return eLump_Planes; }

        // data fields
        point3d_t       n;      ///< plane normal
        float           d;      ///< distance from origin along normal
};



/// texture information
struct texture_path_t : public lump_object_t {
        ~texture_path_t(void) throw();
        eLumpType getType(void) const throw() { return eLump_Textures; }
        void dump(void) const throw() {
                        DPRINTF("  flag: 0x%08x  content: 0x%08x  path: %s",
                            flags, contents, name);
                }

        // data fields
        char            name[64];       ///< name
        int32_t         flags;
        int32_t         contents;
};



/// color struct
/// TODO: centralize this somewhere?  now redundant with glut::color_t
struct color_t {
        byte_t          red;
        byte_t          green;
        byte_t          blue;
        byte_t          alpha;
};



/// vertex information
struct vertex_t : public lump_object_t {
        ~vertex_t(void) throw();
        eLumpType getType(void) const throw() { return eLump_Vertices; }

        // data fields
        point3d_t       position;
        point3d_t       normal;
        float           texcoord[2][2];
        color_t         color;
};



/// The 3D space-partitioned map.
///
/// <b>Warning:</b> this class is NOT threadsafe!  Use only on an isolated
/// thread.
class Bsp {
public:
        // constructor, destructor ---------------------------------------------
        virtual ~Bsp(void) throw();

        // quake::Bsp class interface methods ----------------------------------
        virtual BspVersion getVersion(void) const throw() = 0;
        virtual const char * getName(void) const throw() = 0;

        /// returns the list of lump types normally expected in BSP maps for
        ///     this vendor.  Sometimes the lumps are empty or missing anyway.
        virtual const vec_lump_type_t& getLumps(void) const throw() = 0;

        /// returns 0 if lump does not exist, or if lump exists but is empty.
        /// returns -1 if lump exists but contains an unknown number of objects.
        virtual int getLumpObjectCount(IN eLumpType type) = 0;

        /// resets lump object iteration to the first of the specified type.
        ///     Will silently fail if lump type does not exist.
        virtual void startLumpIteration(IN eLumpType type) = 0;

        /// call this to iterate.  Returns NULL at end of iteration.  Returns
        ///     NULL immediately if lump does not exist or is empty.
        virtual const lump_object_t * getNextLumpObject(void) = 0;

        // static factory methods ----------------------------------------------
        static smart_ptr<Bsp> load(IN smart_ptr<nstream::Stream>& stream);
};



};      // quake namespace



#endif  // WAVEPACKET_QUAKE_BSP_H__