glfCubeMap.hh

/*
 This file is part of the BIAS library (Basic ImageAlgorithmS).

 Copyright (C) 2003-2009    (see file CONTACT for details)
 Multimediale Systeme der Informationsverarbeitung
 Institut fuer Informatik
 Christian-Albrechts-Universitaet Kiel


 BIAS is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as published by
 the Free Software Foundation; either version 2.1 of the License, or
 (at your option) any later version.

 BIAS is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public License
 along with BIAS; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

#ifndef __glfCubeMap_hh__
#define __glfCubeMap_hh__

#include "glfTexture.hh"

namespace BIAS {

  /**
   *  \brief A cube map texture.
   *
   * \note The <code>Allocate</code> methods need not be called, if one
   * of the <code>Upload...</code> methods is used.
   * \ingroup g_openglframework 
   * \author jkollmann
   */
  class BIASOpenGLFramework_EXPORT glfCubeMap : public glfTexture {
  public:
    glfCubeMap();

    /**
     * Uploads a BIAS::Image to a mipmap of one side of the cube map.
     * If the given <code>internalFormat</code> is 0, the internal format is
     * chosen based on the storage type and color model of the image.
     *
     * \attention The uploaded texture will contain the image upside down
     * according to the OpenGL specifications. You can fix this by either
     * flipping the image before uploading it, or by adjusting the texture
     * coordinates.
     *
     * The 'target' defines the side of the cube map, and must be one of
     * the following values:
     * GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X,
     * GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y,
     * GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
     */
    void UploadImage(GLenum target, const BIAS::ImageBase& image,
                     GLenum internalFormat = 0,
                     int mipmap = 0);

    /**
     * Uploads an image loaded from a file to a mipmap of one side of the cube
     * map. If the given <code>internalFormat</code> is 0, the internal format
     * is chosen based on the storage type and color model of the image.
     *
     * \attention The uploaded texture will contain the image upside down
     * according to the OpenGL specifications. You can fix this by either
     * flipping the image before uploading it, or by adjusting the texture
     * coordinates.
     */
    void UploadImageFromFile(GLenum target, const std::string& fileName,
                             GLenum internalFormat = 0,
                             int mipmap = 0);

    /**
     * Creates a cube map with undefined content. This can be used
     * for cube maps in conjuction with framebuffer objects.
     *
     * See <code>glTexImage2D</code> documentation for a list of
     * valid internal formats.
     */
    void Allocate(int width, int height,
                  GLenum internalFormat, int mipmap = 0);

    /**
     * Creates a cube map with undefined content. This can be used
     * for cube maps in conjuction with framebuffer objects.
     *
     * The internal format is chosen based on the given BIAS storage
     * type and color model.
     */
    void Allocate(int width, int height,
                  ImageBase::EStorageType storageType,
                  ImageBase::EColorModel colorModel,
                  int mipmap = 0);

    /**
     * Copies the pixels of a mipmap of a side of the cube map to a BIAS::ImageBase.
     * The image will be initialized with the size of the texture and the appropriate
     * number of channels based on the textures internal format.
     *
     * \attention The given image must have a valid storage type. The easiest way
     * is to pass a BIAS::Image<T>. Storage type ST_double is not supported.
     *
     * \attention The color model of the image is not modified! (TODO?)
     *
     * \attention The returned image will contain the texture upside down
     * according to the OpenGL specifications. You can fix this by either
     * flipping the image after calling this method or by rendering the
     * scene upside down.
     */
    void CopyToImage(GLenum target, ImageBase& image, int mipmap = 0);

    /**
     * Copies the pixels of a mipmap of a side of the cube map to a BIAS::ImageBase
     * and interprets the texture using the given format. Can be used to
     * only copy one channel of the texture to an image.
     * Valid formats are:
     *   GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA,
     *   GL_RGB, GL_BGR, GL_RGBA, GL_BGRA,
     *   GL_LUMINANCE, GL_LUMINANCE_ALPHA
     *
     * \attention The returned image will contain the texture upside down
     * according to the OpenGL specifications. You can fix this by either
     * flipping the image after calling this method or by rendering the
     * scene upside down.
     */
    void CopyChannelsToImage(GLenum target, ImageBase& image,
                             GLenum format, int mipmap = 0);

    /**
     * Returns the width of a mipmap of each side of the cube map.
     */
    int GetWidth(int mipmap = 0) const;

    /**
     * Returns the height of a mipmap of each side of the cube map.
     */
    int GetHeight(int mipmap = 0) const;
  };
  
} // namespace BIAS

#endif // __glfCubeMap_hh__