juce/source/src/gui/graphics/imaging/juce_ImageFileFormat.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_IMAGEFILEFORMAT_JUCEHEADER__
  27 #define __JUCE_IMAGEFILEFORMAT_JUCEHEADER__
  28
  29 #include "juce_Image.h"
  30 #include "../../../io/files/juce_File.h"
  31 #include "../../../io/streams/juce_InputStream.h"
  32 #include "../../../io/streams/juce_OutputStream.h"
  33
  34
  35 //==============================================================================
  36 /**
  37     Base-class for codecs that can read and write image file formats such
  38     as PNG, JPEG, etc.
  39
  40     This class also contains static methods to make it easy to load images
  41     from files, streams or from memory.
  42
  43     @see Image, ImageCache
  44 */
  45 class JUCE_API  ImageFileFormat
  46 {
  47 protected:
  48     //==============================================================================
  49     /** Creates an ImageFormat. */
  50     ImageFileFormat()                   {}
  51
  52 public:
  53     /** Destructor. */
  54     virtual ~ImageFileFormat()          {}
  55
  56     //==============================================================================
  57     /** Returns a description of this file format.
  58
  59         E.g. "JPEG", "PNG"
  60     */
  61     virtual String getFormatName() = 0;
  62
  63     /** Returns true if the given stream seems to contain data that this format
  64         understands.
  65
  66         The format class should only read the first few bytes of the stream and sniff
  67         for header bytes that it understands.
  68
  69         @see decodeImage
  70     */
  71     virtual bool canUnderstand (InputStream& input) = 0;
  72
  73     /** Tries to decode and return an image from the given stream.
  74
  75         This will be called for an image format after calling its canUnderStand() method
  76         to see if it can handle the stream.
  77
  78         @param input    the stream to read the data from. The stream will be positioned
  79                         at the start of the image data (but this may not necessarily
  80                         be position 0)
  81         @returns        the image that was decoded, or an invalid image if it fails.
  82         @see loadFrom
  83     */
  84     virtual Image decodeImage (InputStream& input) = 0;
  85
  86     //==============================================================================
  87     /** Attempts to write an image to a stream.
  88
  89         To specify extra information like encoding quality, there will be appropriate parameters
  90         in the subclasses of the specific file types.
  91
  92         @returns        true if it nothing went wrong.
  93     */
  94     virtual bool writeImageToStream (const Image& sourceImage,
  95                                      OutputStream& destStream) = 0;
  96
  97     //==============================================================================
  98     /** Tries the built-in decoders to see if it can find one to read this stream.
  99
 100         There are currently built-in decoders for PNG, JPEG and GIF formats.
 101
 102         The object that is returned should not be deleted by the caller.
 103
 104         @see canUnderstand, decodeImage, loadFrom
 105     */
 106     static ImageFileFormat* findImageFormatForStream (InputStream& input);
 107
 108     //==============================================================================
 109     /** Tries to load an image from a stream.
 110
 111         This will use the findImageFormatForStream() method to locate a suitable
 112         codec, and use that to load the image.
 113
 114         @returns        the image that was decoded, or an invalid image if it fails.
 115     */
 116     static Image loadFrom (InputStream& input);
 117
 118     /** Tries to load an image from a file.
 119
 120         This will use the findImageFormatForStream() method to locate a suitable
 121         codec, and use that to load the image.
 122
 123         @returns        the image that was decoded, or an invalid image if it fails.
 124     */
 125     static Image loadFrom (const File& file);
 126
 127     /** Tries to load an image from a block of raw image data.
 128
 129         This will use the findImageFormatForStream() method to locate a suitable
 130         codec, and use that to load the image.
 131
 132         @returns        the image that was decoded, or an invalid image if it fails.
 133     */
 134     static Image loadFrom (const void* rawData,
 135                            const int numBytesOfData);
 136
 137 };
 138
 139 //==============================================================================
 140 /**
 141     A subclass of ImageFileFormat for reading and writing PNG files.
 142
 143     @see ImageFileFormat, JPEGImageFormat
 144 */
 145 class JUCE_API  PNGImageFormat  : public ImageFileFormat
 146 {
 147 public:
 148     //==============================================================================
 149     PNGImageFormat();
 150     ~PNGImageFormat();
 151
 152     //==============================================================================
 153     String getFormatName();
 154     bool canUnderstand (InputStream& input);
 155     Image decodeImage (InputStream& input);
 156     bool writeImageToStream (const Image& sourceImage, OutputStream& destStream);
 157 };
 158
 159
 160 //==============================================================================
 161 /**
 162     A subclass of ImageFileFormat for reading and writing JPEG files.
 163
 164     @see ImageFileFormat, PNGImageFormat
 165 */
 166 class JUCE_API  JPEGImageFormat  : public ImageFileFormat
 167 {
 168 public:
 169     //==============================================================================
 170     JPEGImageFormat();
 171     ~JPEGImageFormat();
 172
 173     //==============================================================================
 174     /** Specifies the quality to be used when writing a JPEG file.
 175
 176         @param newQuality  a value 0 to 1.0, where 0 is low quality, 1.0 is best, or
 177                            any negative value is "default" quality
 178     */
 179     void setQuality (float newQuality);
 180
 181     //==============================================================================
 182     String getFormatName();
 183     bool canUnderstand (InputStream& input);
 184     Image decodeImage (InputStream& input);
 185     bool writeImageToStream (const Image& sourceImage, OutputStream& destStream);
 186
 187 private:
 188     float quality;
 189 };
 190
 191 //==============================================================================
 192 /**
 193     A subclass of ImageFileFormat for reading GIF files.
 194
 195     @see ImageFileFormat, PNGImageFormat, JPEGImageFormat
 196 */
 197 class JUCE_API  GIFImageFormat  : public ImageFileFormat
 198 {
 199 public:
 200     //==============================================================================
 201     GIFImageFormat();
 202     ~GIFImageFormat();
 203
 204     //==============================================================================
 205     String getFormatName();
 206     bool canUnderstand (InputStream& input);
 207     Image decodeImage (InputStream& input);
 208     bool writeImageToStream (const Image& sourceImage, OutputStream& destStream);
 209 };
 210
 211
 212 #endif   // __JUCE_IMAGEFILEFORMAT_JUCEHEADER__