viewport.h

Go to the documentation of this file.

/*
 * viewport.h
 *
 * Copyright (C) 2008,2009,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.
 *
 *
 * Basic support for multiple viewports.  This is so that (for example) multiple
 * people can play at the same physical machine.
 */

#ifndef WAVE_GLUT_VIEWPORT_H__
#define WAVE_GLUT_VIEWPORT_H__

// includes --------------------------------------------------------------------
#include "common/common.h"
#include "geometry/geometry_2d.h"
#include "threadsafe/smart_ptr.h"


namespace view {


////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup wave_glut
/// \defgroup viewport
///
/// \n
/// This library defines objects to help clients manage multiple viewports on
/// a single window or screen.  A common use case is a client wanting to
/// present multiple different 3D scenes on the same window.
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/


typedef rect2d_t<int> recti_t;

struct render_info_t {
        // constructor, manipulators
        render_info_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        width = height = 0;
                }
        void dump(IN const char * txt) const throw() {
                        DPRINTF("%s (viewport): %d x %d", txt, width, height);
                }
        bool isValid(void) const throw() {
                        return ((width > 0) && (height > 0));
                }

        // data fields
        int             width;  ///< viewport width (pixels)
        int             height; ///< viewport height (pixels)
};



///     If you are creating viewports, you'll need an object that supports this
///     interface to handle the per-viewport callbacks for display.
class Host {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Host(void) throw();

        // view::Host class interface methods ----------------------------------

        /// host is being called to render this viewport's 3D scene
        virtual void render3D(IN int id, IN const render_info_t& ri) = 0;

        /// host is being called to render this viewport's 2D overlay.  The
        ///     OpenGL drawing context has already been set for 2D drawing.
        ///     2D coordinates are relative to the viewport (so 0,0 is the
        ///     top left of the viewport).
        ///     Reminder: this library uses the wavepacket 2D coordinate
        ///     convention, where y=0 is the top of the screen, and positive
        ///     y is down.  This is opposite to the usual OpenGL convention.
        virtual void render2D(IN int id, IN const render_info_t& ri) = 0;
};



///     This object will let you create/destroy viewports as needed.
class Manager {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Manager(void) throw();

        // view::Manager class interface methods -------------------------------
        virtual int getViewportCount(void) const = 0;

        /// render all viewports.  The Manager will make two passes: first all
        ///     viewports will be called on Host::render3D(), then 2D context
        ///     will be set up, and then all viewports will be called on
        ///     Host::render2D().
        virtual void render(IN int windowWidth, IN int windowHeight) = 0;

        /// given an x/y coordinate, who owns it?  Returns -1 if no one owns
        ///     if someone owns, returns the x and y coordinates relative to the
        ///     viewport of that owner.
        virtual int getOwnerOfCoordinate(IN int x, IN int y,
                                IN int width, IN int height,
                                OUT int& ownerX, OUT int& ownerY) = 0;

        /// caller can request a new viewport be created.  Caller is responsible
        ///     for providing the ID of the new viewport.  Returns false on
        ///     failure (fails if ID is already in use).  Viewport IDs must be
        ///     greater than zero.
        virtual bool createViewport(IN int id,
                                smart_ptr<Host> host) = 0;

        /// remove the specified viewport.  Returns false on failure (no
        ///     viewport with the specified ID found).
        virtual bool removeViewport(IN int id) = 0;

        // static factory methods ----------------------------------------------
        static smart_ptr<Manager> create(void);
};



};      // view namespace


#endif  // WAVE_GLUT_VIEWPORT_H__