annotate src/Modules/Output/Graphics/Devices/GraphicsOutputDevice.h @ 228:82e0dc3dfd16

- All \t to two spaces (style guide compliance)

// Copyright 2006, Willem van Engen
//
// AIM-C: A C++ implementation of the Auditory Image Model
// http://www.acousticscale.org/AIMC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef __GRAPHICS_OUTPUT_DEVICE_H__
#define __GRAPHICS_OUTPUT_DEVICE_H__

#include "Support/Parameters.h"

/*!
 * \class GraphicsOutputDevice "Output/GraphicsOutputDevice.h"
 * \brief General output device class
 *
 * This class provides basic drawing primitives in a device-independent manner.
 * It is structured like the OpenGL interface. Following is an example drawing
 * five horizontal lines, with the colour changing between red and blue over
 * time.
 * \code
 *  GraphicsOutputDevice oOutput = static_cast<GraphicsOutputDevice>(new GraphicsOutputDeviceSomething());
 *  unsigned int a=0;
 *  ...
 *  oOutput->Start();
 *  while ( bIsRunning ) {
 *    // Start a drawing operation
 *    oOutput->gGrab();
 *    // Draw five horizontal lines
 *    for (int y=0; y<5; y++) {
 *      // Start a new line
 *      oOutput->gBegin();
 *      // Give each line it's own colour
 *      oOutput->gColor3f( (a%255)/255, 0, 1-(a%255)/255 );
 *      // Draw the line
 *      oOutput->gVertex2f(0, y);
 *      oOutput->gVertex2f(1, y);
 *      // End the line
 *      oOutput->gEnd();
 *    }
 *    oOutput->gRelease();
 *    Sleep(1);
 *    a++;
 *  }
 *  oOutput->Stop();
 * \endcode
 *
 * This class includes some basic overloading definitions to ease the
 * children's implementation. Note that the basic operations that need
 * implementation are glVertex3f(x,y,z) and glColor(r,g,b).
 */
class GraphicsOutputDevice {
 public:
  GraphicsOutputDevice(AimParameters *pParam);
  virtual ~GraphicsOutputDevice() { };

  /*! \brief Initialize the module, sets up everything to Start().
   *  \return true on success, false on error
   *
   *   Initialize() needs to be called before any other function.
   *
   *  This method is called in it's form as displayed here by the GraphicsView,
   *  but you may want to setup your own Initialize(...) function with
   *  different arguments and call it yourself.
   *
   *  Thus make sure you do all memory allocations here. They can be cleaned
   *  up by the destructor. Because Initialize() may fail, it's not put in
   *  the constructor, so it can return a value.
   *
   *  \sa Module::Initialize()
   */
  virtual bool Initialize(unsigned int iVerticesMax) { return true; };
  /*! \overload
   *  This function reloads the parameters; make sure to have at least the
   *  function with maximum parameters called once.
   */
  virtual bool Initialize() { return true; };

  /*! \brief Create a new drawing
   *  Run this before any other drawing command.
   *  \sa glRelease()
   */
  virtual void gGrab() = 0;

  //! \brief Start a new vertex group for drawing a line strip
  virtual void gBeginLineStrip() = 0;
  //! \brief Start a new vertex group for drawing a quad strip
  virtual void gBeginQuadStrip() = 0;

  /*! \brief Specify a vertex to draw
   *  \param[in] x X-coordinate of the vertex
   *  \param[in] y Y-coordinate of the vertex
   *  \param[in] z Z-coordinate of the vertex
   *  \param[in] r Red component of colour
   *  \param[in] g Green component of colour
   *  \param[in] b Blue component of colour
   *
   *  Currently, only lines are implemented.
   */
  virtual void gVertex3f(float x, float y, float z, float r, float g, float b);

  /*! \overload
   *  This will add a vertex with the last specified colour.
   */

  virtual void gVertex3f(float x, float y, float z) = 0;
  /*! \overload
   *  This will add a vertex in the 2d-plane with z=0.
   */

  virtual void gVertex2f(float x, float y, float r, float g, float b);

  /*! \overload
   *  This will add a vertex in the 2d-plane with z=0 with the last
   *  specified colour.
   */
  virtual void gVertex2f(float x, float y);

  /*! \brief Sets the current colour
   *  \param[in] r Red component
   *  \param[in] g Green component
   *  \param[in] b Blue component
   */
  virtual void gColor3f(float r, float g, float b) = 0;

  //! \brief End a vertex group
  virtual void gEnd() = 0;

  /*! \brief Render a text string
   *  \param[in] x X-coordinate of the text's alignment point
   *  \param[in] y Y-coordinate of the text's alignment point
   *  \param[in] z Z-coordinate of the text's alignment point
   *  \param[in] sStr Text to render
   *  \param[in] bRotated \c true for vertically rotated text
   *
   *  Current alignment is horizontal:left and vertical:bottom
   *  \todo Allow multiple alignment points
   */
  virtual void gText3f(float x,
                       float y,
                       float z,
                       const char *sStr,
                       bool bRotated = false) = 0;

  /*! \overload
   *  This will render a text string in the 2d-plane with z=0.
   */
  virtual void gText2f(float x,
                      float y,
                      const char *sStr,
                      bool bRight = false);

  /*! \brief Finish drawing
   *  Call this when a drawing is finished. It also makes sure that the
   *  rendering is actually done.
   *  \sa glGrab()
   */
  virtual void gRelease() = 0;

  /*! \brief Called when animation starts
   *
   *  You may wonder what Start() and Stop() do here. Some implementations
   *  may want to behave differently with respect to updating, if an
   *  animation is running or not (e.g. updating).
   */
  virtual void Start() { m_bRunning = true; }

  //! \brief Called when animation stops
  virtual void Stop()  { m_bRunning = false; }

 protected:
  //! \brief True when animation is running
  bool m_bRunning;
  //! \brief Parameter store
  AimParameters *m_pParam;

  //! \brief Pixel Formats
  enum PixelFormat {AIM_PIX_FMT_RGB24_32, AIM_PIX_FMT_RGB24_24};
};

#endif /* __GRAPHICS_OUTPUT_DEVICE__ */