prism.h

Go to the documentation of this file.

/*
 * prism.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.
 *
 *
 * 3D Prisms
 */

#ifndef WAVEPACKET_PRISM_H__
#define WAVEPACKET_PRISM_H__

// includes --------------------------------------------------------------------
#include "geometry_3d.h"
#include "matrix_4.h"


/// \ingroup geometry
/*@{*/


/// a prism is a 3D object, basically a polygon in some plane with some
///     extent in the plane normal direction.  See wikipedia for the general
///     definition: http://en.wikipedia.org/wiki/Prism_(geometry)
///     In particular, this is a \b right prism.
/// This class (prism_base_t) is templated, so that the client can decide the
///     max size of the vertex array.  Given a polygonal base of N points, you
///     will need 2N vertices.
/// The array of points has a specific convention:
///     point[2 * i] is the vertex on the "floor" (y = 0)
///     point[(2 * i) + 1] is the vertex on the ceiling (y = height above the
///             point[2 * i] vertex)
/// So for instance, any consecutive sequence of 4 points starting with even
///     index is guaranteed to be a planar rectangle.  This is a very helpful
///     property of prisms.
/// \b WARNING: the xz-plane, y-extent convention is recommended for basic
///     prisms.  However, prisms can be transformed by arbitrary 3D
///     transformations (see matrix4_t).  So you can't assume that an
///     odd-indexed point is only translated in the y-direction from its
///     even-indexed base, for instance.  However, consecutive sequences of 4
///     points starting with even index will always be a planar rectangle, even
///     when transformed.
template <class Size>
struct prism_base_t {
        // constructor, manipulators
        prism_base_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        nVertices = 0;
                }
        bool isValid(void) const throw() {
                        return (nVertices > 2) &&
                               (2 * nVertices < Size::eMaxCount);
                }
        void setVertexCount(IN int N) {
                        ASSERT_THROW(N > 5 &&           // at least 3-sided
                                     (0 == (N % 2)) &&  // must be even
                                     N <= Size::eMaxCount,
                            "Invalid prism vertex count: " << N);
                        nVertices = N;
                }

        // data fields
        point3d_t               points[Size::eMaxCount];
        int                     nVertices;
};



class DefaultSize {
public:
        enum eConstants {
                eMaxCount               = 16
        };
};



/// a default prism class, supporting up to 16 points (supports prisms based
///     on polygons up to 8 sides).
typedef prism_base_t<DefaultSize> prism_t;



/// creates a 3D prism whose base is a regular N-polygon, with specified radius
///     and height.  Caller must provide an array big enough to hold 2*nSides
///     points.  That array is populated on output.  The polygons are in the
///     xz plane, separated by distance height in the y direction.
void createRegularPrism(IN int nSides,
                        IN float radius,
                        IN float height,
                        IO point3d_t * points);



/// helper method to create a regular prism
template <class Size>
void createRegularPrism
(
IN int nSides,
IN float radius,
IN float height,
OUT prism_base_t<Size>& prism
)
{
        prism.setVertexCount(2 * nSides);
        createRegularPrism(nSides, radius, height, prism.points);
}



/// transforms a prism by a matrix4_t transformation
template <class Size>
prism_base_t<Size>
operator *
(
IN const matrix4_t& T,
IN const prism_base_t<Size>& prism
)
{
        ASSERT_THROW(prism.isValid(), "Invalid prism being transformed");
        prism_base_t<Size> outPrism;
        outPrism.setVertexCount(prism.nVertices);
        transformPoints(T, prism.nVertices, prism.points, outPrism.points);
        return outPrism;
}



#endif  // WAVEPACKET_PRISM_H__