image-base.h

Go to the documentation of this file.

/*
 * image-base.h
 *
 * Copyright (C) 2009  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.
 *
 *
 * This is the start of the dependency tree.  It defines a simple image object,
 * and the interface used by image loaders.
 */

#ifndef WAVEPACKET_IMAGE_BASE_H__
#define WAVEPACKET_IMAGE_BASE_H__

// includes --------------------------------------------------------------------
#include "common/common.h"
#include "common/wave_ex.h"


namespace nstream {
class Manager;  // forward declaration
class Stream;
};



namespace media {

/// \ingroup wave_image
/*@{*/

////////////////////////////////////////////////////////////////////////////////
///
/// \defgroup image_base Base Image Library
///
/// This library is used only by clients that are writing an image loader.
/// If you just want to load images, use the \ref wave_image library instead.
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/


/// refers to what sort of data you have per-pixel in the image
enum eColorFormat {
        eColorFormat_Grayscale          = 1,    ///< grayscale, usually 8 bit
        eColorFormat_GrayAlpha          = 2,    ///< gray plus alpha, 16 bit?

        eColorFormat_RGB                = 5,    ///< RGB, usually 24 bit
        eColorFormat_RGBA               = 6,    ///< RGBA, usually 32 bit

        // keep this last!
        eColorFormat_Invalid            = 0
};


/// this is a basic image object.  Contains some image metadata as well as the
///     actual pixel data.  Use the color_format and bytes_per_pixel to
///     determine how to interpret the raw data.
struct image_t {
        // constants
        enum eConstants {
                eMaxString      = 8
        };

        // constructor, destructor
        image_t(void) throw() : data(NULL) { this->clear(); }
        ~image_t(void) throw() { this->clear(); }

        // manipulators, accessors
        void clear(void) throw() {
                        width = height = 0;
                        bit_depth = 0;
                        color_format = eColorFormat_Invalid;
                        bytes_per_pixel = 0;
                        imageType[0] = 0;
                        if (data) {
                                delete[] data;
                                data = NULL;
                        }
                }
        void setImageType(IN const char * type) throw() {
                        strncpy(imageType, type, eMaxString);
                        imageType[eMaxString - 1] = 0;
                }
        bool isValid(void) const throw() {
                        return (width > 0 &&
                                height > 0 &&
                                data &&
                                (eColorFormat_Invalid != color_format) &&
                                bit_depth > 0 &&
                                bytes_per_pixel > 0);
                }
        void dump(IN const char * txt) const throw();
        void allocate(void) {
                        ASSERT(!data, "already allocated?");
                        ASSERT(width > 0, "bad width: %d", width);
                        ASSERT(height > 0, "bad height: %d", height);
                        ASSERT(bytes_per_pixel > 0, "Bad bpp: %d", bytes_per_pixel);

                        long nBytes = width * height * bytes_per_pixel;
                        data = new byte_t[nBytes];
                        ASSERT_THROW(data, "out of memory");
                }

        // data fields
        int32_t         width;
        int32_t         height;
        int32_t         bit_depth;
        eColorFormat    color_format;
        int32_t         bytes_per_pixel;
        char            imageType[eMaxString];
        byte_t *        data;
};



////////////////////////////////////////////////////////////////////////////////
//
//      API for image loaders
//
//      If you want to support a new kind of image and make it available to the
//      media::loadImage() call, these are the interfaces to work with.
//
////////////////////////////////////////////////////////////////////////////////

/// anyone wanting to support loading an image type must provide this interface.
/// <b>Warning to implementers: keep your image loaders entirely stateless!</b>
/// ImageLoader objects can be called on any thread, so they should be
///     threadsafe.  In practice that is easy so long as the loader is
///     stateless.  (stateless means no static or class member variables--the
///     only state is the image being loaded, or other state on the stack).
class ImageLoader {
public:
        // virtual constructor -------------------------------------------------
        virtual ~ImageLoader(void) throw();

        // media::ImageLoader class interface methods --------------------------

        /// tell us the name of yourself
        virtual const char * getLoaderName(void) const throw() = 0;

        /// image loader should return true if this is an image this loader can
        ///     load.
        virtual bool canLoadImage(IN nstream::Manager * mgr,
                                IN const char * name) const = 0;

        /// here the loader actually loads
        virtual void load(IN nstream::Stream * stream,
                                OUT image_t& image) const = 0;
};



};      // media namespace



#endif  // WAVEPACKET_IMAGE_BASE_H__