gls_image.h

Go to the documentation of this file.

#ifndef _GLS_IMAGE_H
#define _GLS_IMAGE_H

/*! \file gls_image.h

\brief  This header defines the GlsImage class which encapsulates textures
        in the GL Studio DO-178B Runtime Library.

\par Copyright Information
Copyright (C) 1999-2012 The DiSTI Corporation<br>
Orlando, FL USA<br>
All rights reserved.<br>

  This file is copyrighted software and contains proprietary trade secrets of
DiSTI, and embodies substantial creative efforts as well as confidential
information, ideas, and expressions.

  Permission to use, and copy this software and its documentation for any
purpose is hereby granted per the Distribution Agreement and/or the Licensing
Agreement signed with DiSTI. This permission is granted provided that:
    1.  The above copyright notice appears in all copies.
    2.  That both the copyright notice and this permission notice appear in
        the supporting documentation.
    3.  That the names DiSTI and GL Studio not be used in advertising or
        publicity pertaining to distribution of the software without specific,
        written prior permission of DiSTI.
 
  Permission to modify the software is granted, but not the right to
distribute the source code whether modified, or non-modified.  Modifying the
software might invalidate the DO-178B certification package.

  Permission to distribute binaries produced by compiling source code, or
modified source code is granted, provided you:
    1.  Provide your name and address as the primary contact for the support
        of your modified version.
    2.  Retain our contact information in regard to use of the base software. 

   DiSTI does not provide warranty for this software or guarantee that it
satisfies any specification or requirement unless otherwise stated in a
specific contractual arrangement between the customer and DiSTI.

*/

#include "gls_include.h"
#include "gls_state_manager.h"
#include "gls_pointer_array.h"
#include "gls_class_invariant.h"

/** Encapsulates a 2D image
  * \invariant INVALID_TEXTURE_HANDLE != _textureHandle,
  *            GlsImageInputPixelFormatIsValid( _inputPixelFormat ),
  *            _pixelSize > 0,
  *            ( _height > 0 ) && IsPowerOf2( _height ),
  *            ( _width  > 0 ) && IsPowerOf2( _width  ),
  *            _imageList != GLS_NULL
  *            ( ( _maxImageWidth > 0u ) && IsPowerOf2( _maxImageWidth ) ),
  *            GlsAssert( GLS_NULL != _scanlineImageData != GLS_NULL
  */
class GlsImage
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsImage )

    /** enumeration of possible image compression codecs */
    enum ImageCodec
    {
        IMAGE_CODEC_RAW,     /**< Image data is not compressed */
        IMAGE_CODEC_RLE,     /**< Image data is compressed with RLE ( Run Length Encoded ) */

        #if defined( GLS_DEBUG )
            IMAGE_CODEC_INVALID    /**< Invalid image codec ( GLS_DEBUG only ) */
        #endif
    };

    /** enumeration of supported input pixel formats */
    enum InputPixelFormat
    {
        INPUT_PIXEL_FORMAT_RGB,         /**< red, green, blue */
        INPUT_PIXEL_FORMAT_RGBA,        /**< red, green, blue, alpha */
        INPUT_PIXEL_FORMAT_ALPHA,       /**< alpha */

        #if defined( GLS_DEBUG )
            INPUT_PIXEL_FORMAT_INVALID        /**< invalid pixel format ( GLS_DEBUG only ) */
        #endif
    };

    /** This structure is generated and contains information needed to
      * reconstruct an inline generated image.
      */
    struct InlineImage
    {
        const GlsUInt32        width;              /**< Width of image in pixels. Must be a power of 2 */
        const GlsUInt32        height;             /**< Height of image in pixels. Must be a power of 2 */
        const InputPixelFormat inputPixelFormat;   /**< Input Pixel format of image */
        const ImageCodec       codec;              /**< CODEC used to compress image */
        const GlsUInt32        crc;                /**< CRC of uncompressed image data */
        const GlsUInt32        imageDataSize;      /**< Size of data (compressed) */
        const GlsUInt32        lineLength;         /**< Length of each line of inline data, in bytes */
        const GlsUChar* const *imageData;          /**< inline image data */

        #if defined( GLS_DEBUG )
            /** Determine if the inline image structure is valid
            * \return GLS_TRUE if valid else GLS_FALSE
            * \pre none
            * \post none
            */
            GlsBool IsValid( void ) const;
        #endif // GLS_DEBUG
    };

    /** initialization parameters for GlsImage subsystem */
    struct InitParameters
    {
        const GlsUInt32 maxNumImages;   /**< maximum number of unique images to support in the image list */
        const GlsUInt32 maxImageWidth;  /**< maximum width in pixels of an image to support (>0, power of 2)*/

        #if defined( GLS_DEBUG )
            /** Determine if the initialization parameters are valid ( GLS_DEBUG only )
              * \return GLS_TRUE if valid else GLS_FALSE
              * \pre none
              * \post none
              */
            GlsBool IsValid( void ) const;
        #endif // GLS_DEBUG
    };

    /**  Initialize the GlsImage subsystem. This is a one time call that must be
      * made before the image subsystem can be used.
      * \param initParameters initialization parameters for GlsImage subsystem
      * \pre GlsImage subsystem has not already been initialized, initParameters.IsValid()
      * \post GlsImage subsystem intermediate image buffers and image list are allocated
      */
    static void Initialize( const InitParameters &initParameters );

    /** Get an Image object with the given GlsInlineImage data.
      * If checkForDuplicate is GLS_TRUE, this method checks 
      * to see if an image has already been constructed for the
      * GlsInlineImage and if found, returns the previously
      * constructed image.
      * \param inlineImage GlsInlineImage in question
      * \param checkForDuplicate GLS_TRUE to check if this inline image is a
      *        duplicate of an existing image else GLS_FALSE
      * \return image corresponding to given inline image
      * \pre inlineImage.IsValid(), a GlsStateManager instance does not yet exist,
      *      the GlsImage subsytem has been initialized,
      *      inlineImage.width <= _maxImageWidth
      * \post new image constructed as needed
      */
    static GlsImage* GetGlsImageFromInlineImage( const InlineImage &inlineImage, const GlsBool checkForDuplicate );

    /** Make this image the active GL texture. 
      * \pre glIsTexture( _textureHandle ) == GL_TRUE
      * \post image is bound to GL
      */
    void BindTexture( GlsStateManager &gl ) const;

    /** Determine if this image matches the given inline image
      * \param inlineImage inline image in question
      * \return GLS_TRUE if matches inline image else GLS_FALSE
      * \pre inlineImage.IsValid()
      * \post none
      */
    GlsBool IsEqual( const InlineImage &inlineImage ) const;

protected:
    /** This class implements a list of image pointers used for maintaining
      * a list of images that have been instantiated.  This list is used when checking
      * for duplicate images
      * \invariant _images invariant holds,
      *            _numImages <= _images.GetSize(),
      *            invariant holds for all images in the list
      */
    class ImageList
    {
    public:
        GLS_CLASS_INVARIANT_DECLARATION( ImageList )

        /** Constructor - create an empty image list
          * \param maxNumImages maximum number of image pointers to hold in list
          * \pre none
          * \post instance created, image list is empty
          */
        ImageList( const GlsUInt32 maxNumImages );

        /** Add an image to the image list
          * \param image image to add
          * \pre image != GLS_NULL, image is not already in the list, image list
          *      has room for one more image
          * \post image is added to the list
          */
        void AddImage( GlsImage* const image );

        /** Find an image in the list that corresponds to the given inline image
          * \param inlineImage inline image in question
          * \return pointer to corresponding image else GLS_NULL if not in list
          * \pre inlineImage.IsValid()
          * \post none
          */
        GlsImage* FindImageFromInlineImage( const InlineImage &inlineImage ) const;

    protected:
        GlsUInt32         _numImages;    /**< number of images added to _images array */
        GlsPointerArray   _images;       /**< array of image pointers */

        #if defined( GLS_DEBUG )
            /** Find the given image pointer in the image list ( GLS_DEBUG only )
              * \param image image pointer in question
              * \return GLS_TRUE if found else GLS_FALSE
              * \pre image != GLS_NULL
              * \post none
              */
            GlsBool FindImagePointer( const GlsImage* const image ) const;
        #endif // GLS_DEBUG

        /** Destructor - shall never be called
          * \pre none
          * \post none 
          */
        virtual ~ImageList();

    private:
        // Disable implicit generated Members
        ImageList& operator=( const ImageList &rhs );
        ImageList( const ImageList &src );
    };

    /** value indicating invalid texture handle */
    static const GLuint INVALID_TEXTURE_HANDLE  =   0u;     

    /** corresponds to layout of a GL_RGBA8 pixel */
    enum
    {
        PIXEL_GL_RED_COMPONENT    = 0u,  /**< GL_RGBA8 - red component */
        PIXEL_GL_GREEN_COMPONENT,        /**< GL_RGBA8 - green component */
        PIXEL_GL_BLUE_COMPONENT,         /**< GL_RGBA8 - blue component */
        PIXEL_GL_ALPHA_COMPONENT,        /**< GL_RGBA8 - alpha component */
        NUM_BYTES_PER_PIXEL_GL           /**< number of bytes per pixel in GL texture data */
    };
    
    /** number of bytes per input pixel for INPUT_PIXEL_FORMAT_RGB */
    static const GlsUInt32 NUM_BYTES_PER_INPUT_PIXEL_FORMAT_RGB     = 3u;
    /** number of bytes per input pixel for INPUT_PIXEL_FORMAT_RGBA */
    static const GlsUInt32 NUM_BYTES_PER_INPUT_PIXEL_FORMAT_RGBA    = 4u;
    /** number of bytes per input pixel for INPUT_PIXEL_FORMAT_ALPHA */
    static const GlsUInt32 NUM_BYTES_PER_INPUT_PIXEL_FORMAT_ALPHA   = 1u;

    GLuint                 _textureHandle;     /**< The texture handle of the image, else INVALID_TEXTURE_HANDLE */
    const InputPixelFormat _inputPixelFormat;  /**< Input pixel format of image */
    const GlsUInt32        _width;             /**< width of image in pixels. must be a power of 2 */
    const GlsUInt32        _height;            /**< height of image in pixels. must be a power of 2 */
    const GlsUInt32        _crcValue;          /**< CRC value used to determine if two images are the same */

    static ImageList      *_imageList;         /**< singleton image list */
    static GlsUChar       *_scanlineImageData; /**< intermediate image buffer for RGBA image data
                                                 *  scanline, number of bytes =
                                                 * ( NUM_BYTES_PER_PIXEL_GL * _maxWidth */

    #if defined( GLS_DEBUG )
        static GlsUInt32       _maxImageWidth; /**< maximum allowed texture width ( GLS_DEBUG only )*/
    #endif // GLS_DEBUG

    /** Constructor - create an image from the given inline image
      * \param inlineImage inline image in question
      * \pre inlineImage.IsValid(), the GlsImage subsystem has been initialized,
      *      inlineImage.width <= _maxImageWidth
      * \post image constructed
      */
    GlsImage( const InlineImage &inlineImage );

    /** decode the given inline image and upload to GL
      * \param inlineImage inline image in question
      * \pre inlineImage.IsValid(), inlineImage.codec is either IMAGE_CODEC_RLE or IMAGE_CODEC_RAW,
      *      inlineImage.width <= _maxImageWidth,
      *      inlineImage.inputPixelFormat must be either
      *          INPUT_PIXEL_FORMAT_ALPHA, INPUT_PIXEL_FORMAT_RGB, or INPUT_PIXEL_FORMAT_RGBA
      *      empty texture of appropriate size is created and bound to GL,
      *      the GlsImage subsystem has been initialized
      * \post image is decoded and uploaded to GL
      */
    void DecodeImage( const InlineImage &inlineImage );

    /** Get the number of bytes required per pixel for the given format
      * \param inputPixelFormat format in question
      * \return number of bytes required per pixel for format
      * \pre GlsImageInputPixelFormatIsValid( inputPixelFormat )
      * \post none
      */
    GlsUInt32 PixelSizeFromInputPixelFormat( const GlsImage::InputPixelFormat inputPixelFormat ) const;

    /** Destructor - shall never be called
      * \pre none
      * \post none 
      */
    virtual ~GlsImage();

private:
    // Disable implicit generated Members
    GlsImage& operator=( const GlsImage &rhs );
    GlsImage( const GlsImage &src );
};

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given image codec is valid ( GLS_DEBUG only )
  * \param imageCodec image codec in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsImageCodecIsValid( const GlsImage::ImageCodec imageCodec )
{
    return( ( GlsImage::IMAGE_CODEC_RAW == imageCodec ) ||
            ( GlsImage::IMAGE_CODEC_RLE == imageCodec ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given input pixel format is valid ( GLS_DEBUG only )
  * \param imageCodec image codec in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsImageInputPixelFormatIsValid( const GlsImage::InputPixelFormat inputPixelFormat )
{
    return( ( GlsImage::INPUT_PIXEL_FORMAT_RGB   == inputPixelFormat ) ||
            ( GlsImage::INPUT_PIXEL_FORMAT_RGBA  == inputPixelFormat ) ||
            ( GlsImage::INPUT_PIXEL_FORMAT_ALPHA == inputPixelFormat ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#endif // _GLS_IMAGE_H