/**
\defgroup module_glimg GL Image

The GL Image library is the Unofficial OpenGL SDK library for loading images from files and memory, and converting them into OpenGL textures.

The GL Image library is distributed under the <a href="http://www.opensource.org/licenses/MIT">MIT License</a>.

GL Image is used for two things: loading images into memory and converting those memory images into OpenGL texture objects. This creates three basic divisions in GL Image.

The functions responsible for loading image formats from disk (or from memory) are called \ref module_glimg_loaders "loaders". They are all in the glimg::loaders namespace. There are several loaders available, for various different image file formats. Each kind of loader has its own namespace within the loaders namespace.

The loaded representation of an image file is the glimg::ImageSet object. An glimg::ImageSet, as the name implies, represents multiple images. This allows support for file formats like DDS or KTX that store mipmaps, texture arrays, and/or cubemap faces all within the same file. The \ref module_glimg_imageset "image set object and its associated types" are used to query information about each image within the set.

The images within an glimg::ImageSet can be directly loaded into an OpenGL texture by using the various \ref module_glimg_texture "texture creation functions". Note that use of these functions requires that you use \ref module_glload "GL Load" to initialize your OpenGL context. They also require that a valid OpenGL context is bound.

Basic use of the library is quite simple. The <tt><glimg/glimg.h></tt> header contains all of the important components of the library. To load an image, select a \ref module_glimg_loaders "loader" and use its loading function to load the texture into an glimg::ImageSet object. Then pass this glimg::ImageSet along to glimg::CreateTexture to create the OpenGL texture object for the file.

Here is an example:

\code
#include <memory>
#include <glload/gl_all.h>
#include <glload/gll.hpp>
#include <glimg/glimg.h>

int main(int argc, char *argv[])
{
  //Initialize OpenGL and bind the context
  
  //glload must be initialized for glimg texture creation to work.
  if(glload::LoadFunctions() == glload::LS_LOAD_FAILED)
    //exit in some way
	
  //Loading succeeded. Now load a texture.
  GLuint theTexture = 0;
  try
  {
    std::auto_ptr<glimg::ImageSet> pImgSet(glimg::loaders::stb::LoadFromFile("filename.png"));
    theTexture = glimg::CreateTexture(pImgSet.get(), 0);

  }
  catch(glimg::loaders::stb::StbLoaderException &e)
  {
    //Image file loading failed.
  }
  catch(glimg::TextureGenerationException &e)
  {
    //Texture creation failed.
  }
  
  //Texture loaded successfully.
}
\endcode

**/

/**
\defgroup module_glimg_loaders Image Loaders
\ingroup module_glimg

\brief Functions for loading image files into ImageSet objects.

These function are defined to work for certain specific file formats. You are expected to delete the ImageSet object returned by the loader functions.

If the image loader fails, then it will throw some form of exception that is ultimately derived from std::exception. Each particular loader will have a set of exceptions that it can throw.

All image loaders live in the glimg::loaders namespace. Each kind of loader has its own subnamespace.
**/

/**
\defgroup module_glimg_imageset ImageSet
\ingroup module_glimg

\brief Classes for representing image data.

The ImageSet class represents a set of images that can be bundled together into a texture. Once loaded, an ImageSet is \em immutable; it's data cannot be changed.

ImageSet objects have a dimensionality. This can be 1D, 2D, or 3D. They also have a size for each dimension. Each ImageSet has a specific image format. The format defines the arrangement of pixel data in all of the ImageSet's images.

Individual images within the set can be queried from an ImageSet; these images have the type SingleImage. These objects share the same ImageFormat as the owning ImageSet object. These objects must be deleted \em before the deletion of the ImageSet from which they originate.

You are encouraged to use smart pointers to manage the memory for ImageSet and SingleImage objects.
**/

/**
\defgroup module_glimg_format Image Format
\ingroup module_glimg_imageset

\brief Types for representing the format of image data.

The ImageFormat class describes a particular arrangement of pixel data within an image. There are four enumerations that specify the different facets of an image format. The ImageFormat also includes the byte alignment of each row of the pixel data, regardless of how wide they are.

Not all combinations of image format parameters are valid. To prevent accidental use of invalid combinations, ImageFormat objects are verified upon creation. Invalid combinations of parameters will throw InvalidFormatException, which contains a message describing the problem. The \ref page_glimg_format_validation "rules for image format validation" are available.
**/

/**
\defgroup module_glimg_texture Texture Creation
\ingroup module_glimg

\brief Functions to build textures from ImageSet objects.

The important function of interest is CreateTexture; this takes an ImageSet and generates an OpenGL texture object. There is an overload that can take a pre-created OpenGL texture object as well; you should not have used that texture object before.

There are also query functions that convert an ImageFormat into information that you can use to manually upload parts of an ImageSet. glimg::GetInternalFormat takes an ImageFormat and returns the corresponding OpenGL internal format that you should use in glTex(Sub)Image* or equivalent calls.

glimg::GetUploadFormatType returns an object that can be used to supply the pixel transfer parameters (the second and third to last parameters to glTex(Sub)Image). If you are uploading a compressed texture, you can just use SingleImage::GetImageByteSize to get its size.

There are a number of flags that the user can provide which affect the selection of the OpenGL parameters.
**/

/**
\defgroup module_glimg_creation Image Creation
\ingroup module_glimg

\brief Manual ImageSet creation classes

ImageSet is a closed class; it has no exposed constructor. This is due to the need to ensure that the data generated by \ref module_glimg_loaders "loaders" remains intact and valid. However, it is often useful to be able to either write your own loaders for other forms of data, or simply to create an ImageSet from user generated data.

The ImageCreator class is a factory for generating an ImageSet. Once it has
generated one, that particular class instance cannot be used again.
**/

/**
\defgroup module_glimg_exceptions Exceptions
\ingroup module_glimg

\brief Exceptions thrown by GL Image functions and operations.

Each function that throws describes the exceptions (or base classes thereof) that it will throw. All exceptions are derived from std::exception.
**/

/**
\page page_glimg_format_validation Image Format Validation Rules

Not every combination of image format parameters is considered valid. Some are functionally meaningless or inconsistent, while others are simply not allowed.


**/

