| /* |
| * Project: VizKit |
| * Version: 2.3 |
| |
| * Date: 20090823 |
| * File: VisualImage.h |
| * |
| */ |
| |
| /*************************************************************************** |
| |
| Copyright (c) 2004-2009 Heiko Wichmann (http://www.imagomat.de/vizkit) |
| |
| |
| This software is provided 'as-is', without any expressed or implied warranty. |
| In no event will the authors be held liable for any damages |
| arising from the use of this software. |
| |
| Permission is granted to anyone to use this software for any purpose, |
| including commercial applications, and to alter it and redistribute it |
| freely, subject to the following restrictions: |
| |
| 1. The origin of this software must not be misrepresented; |
| you must not claim that you wrote the original software. |
| If you use this software in a product, an acknowledgment |
| in the product documentation would be appreciated |
| but is not required. |
| |
| 2. Altered source versions must be plainly marked as such, |
| and must not be misrepresented as being the original software. |
| |
| 3. This notice may not be removed or altered from any source distribution. |
| |
| ***************************************************************************/ |
| |
| #ifndef VisualImage_h |
| #define VisualImage_h |
| |
| |
| #include "VisualTypes.h" |
| #include "VisualGraphicTypes.h" |
| #include "VisualObject.h" |
| #include "VisualNotification.h" |
| #include "VisualHistogram.h" |
| #include "VisualThreading.h" |
| |
| namespace VizKit { |
| |
| class VisualString; // Forward declaration (to avoid include of header file). |
| class VisualStyledString; // Forward declaration (to avoid include of header file). |
| class VisualFile; // Forward declaration (to avoid include of header file). |
| class VisualTextureContainer; // Forward declaration (to avoid include of header file). |
| class VisualConvolutionFilter; // Forward declaration (to avoid include of header file). |
| class VisualCamera; // Forward declaration (to avoid include of header file). |
| class VisualItemIdentifier; // Forward declaration (to avoid include of header file). |
| |
| |
| /** |
| * Bitmap raster image. |
| */ |
| class VisualImage : public VisualObject { |
| |
| public: |
| |
| /** |
| * The constructor. |
| */ |
| VisualImage(); |
| |
| /** |
| * The destructor. |
| */ |
| ~VisualImage(); |
| |
| /** |
| * Copy constructor. |
| * @param other Reference to another VisualImage. |
| */ |
| VisualImage(const VisualImage& other); |
| |
| /** |
| * Assignment operator. |
| * @param other Reference to another VisualImage. |
| */ |
| VisualImage& operator=(const VisualImage& other); |
| |
| /** |
| * Copies the current VisualImage and returns a pointer to a new VisualImage. |
| * @remarks Cloning the image returns an image pointing to the same framebuffer data. To create an independent image, use createIndependentCopy(). |
| */ |
| virtual VisualImage* clone(void) const; |
| |
| /** |
| * Creates an independent copy of the image. |
| * @remarks The image copy is independent of the original image. Cloning the image returns an image pointing to the same framebuffer data. |
| */ |
| VisualImage* cloneIndependently(void) const; |
| |
| /** |
| * Initializes the image with a file. |
| * @param aFile Reference to a file. |
| * @return True on success, false on failure. |
| */ |
| bool initWithFile(VisualFile& aFile); |
| |
| /** |
| * Initializes the image with a buffer of ARGB pixel data. |
| * @param argbPixels Pointer to ARGB pixel data. |
| * @param width The width of the pixel data. |
| * @param height The height of the pixel data. |
| * @return True on succes, false on failure. |
| * @remarks No reference to the pixel data is stored, pixel data can be savely disposed after the call. |
| */ |
| bool initWithARGBPixelData(PixelColor* argbPixels, uint32 width, uint32 height); |
| |
| /** |
| * Initializes the image with a data pointer to encoded image data. |
| * @param bufferData A pointer to the data. |
| * @param size The size of the data pointed to in bytes. |
| * @return True on success, false on failure. |
| */ |
| bool initWithEncodedData(const char* const bufferData, size_t size); |
| |
| /** |
| * Initializes the image with a styled string. |
| * @param styledString The styled string to convert into bitmap image. |
| * @return True on success, false on failure |
| */ |
| bool initWithStyledString(VisualStyledString& styledString); |
| |
| #if TARGET_OS_WIN |
| /** |
| * Initializes the image with a resource image. |
| * @param nameId The id of the resource. |
| * @return True on success, false on failure. |
| */ |
| bool initWithResource(int nameId); |
| #endif |
| #if TARGET_OS_MAC |
| /** |
| * Initializes the image with a resource image. |
| * @param name The name of the resource. |
| * @return True on success, false on failure. |
| */ |
| bool initWithResource(const char* name); |
| #endif |
| |
| /** |
| * Initializes the image with an URL. |
| * @param anURL URL of the image. |
| * @param anId Identifier that can be queried to track the progress of this asynchronous initialization. |
| * @return True on success, false on failure. |
| */ |
| bool initWithURL(VisualString& anURL, VisualItemIdentifier& anId); |
| |
| /** |
| * Initializes the image with loaded encoded image data. |
| * @return True on success, false on failure. |
| */ |
| bool initWithLoadedEncodedData(void); |
| |
| /** |
| * Initializes the image with contents of the current screen (framebuffer). |
| * @param clipRect The dimensions and position of the clip rect. |
| * @return True on success, false on failure. |
| */ |
| bool initWithFramebuffer(const BottomLeftPositionedPixelRect& clipRect); |
| |
| /** |
| * Writes the image as PNG encoded data to a file on disk. |
| * @param aVisualFile Access to file the image is to be written into. |
| * @return True on success, false on failure. |
| */ |
| bool writeToPNGFile(VisualFile& aVisualFile) const; |
| |
| /** |
| * Writes the image as PNG encoded data to a file on disk asynchronously. |
| * @param aVisualFile Access to file the image is to be written into. |
| */ |
| void writeToPNGFileAsync(VisualFile& aVisualFile); |
| |
| /** |
| * Writes the image as PNG encoded data to a file on disk asynchronously and deletes the VisualImage afterwards. |
| * @param aVisualFile Access to file the image is to be written into. |
| */ |
| void writeToPNGFileAsyncAndDelete(VisualFile& aVisualFile); |
| |
| /** |
| * Applies a convolution filter to the image. |
| * @param aConvolutionFilter The convolution filter to apply to the image. |
| */ |
| void applyConvolutionFilter(const VisualConvolutionFilter& aConvolutionFilter); |
| |
| /** |
| * Returns the width of the bitmap image (in pixels). |
| * @return The width of the bitmap image (in pixels). |
| */ |
| uint32 getWidth(void) const; |
| |
| /** |
| * Returns the height of the bitmap image (in pixels). |
| * @return The height of the bitmap image (in pixels). |
| */ |
| uint32 getHeight(void) const; |
| |
| /** |
| * Returns the logical width of the texture. |
| * @return The logical width of the texture. |
| */ |
| double getLogicalWidth(void) const; |
| |
| /** |
| * Returns the logical height of the texture. |
| * @return The logical height of the texture. |
| */ |
| double getLogicalHeight(void) const; |
| |
| /** |
| * Draws the image. |
| * @param aVertexChain The chain of vertices with which the image is drawn. |
| * @param debug If true, details of the drawing operation can be traced for diagnostical purposes. |
| */ |
| void draw(const VertexChain* const aVertexChain, bool debug = false); |
| |
| /** |
| * Answers the question whether the image is empty or set. |
| */ |
| bool isEmpty(void) const; |
| |
| /** |
| * Returns the blend mode of the image. |
| * @return The blend mode of the image. |
| */ |
| BlendMode getBlendMode(void) const; |
| |
| /** |
| * Sets the blend mode of the image. |
| * @param aBlendMode The blend mode of the image. |
| */ |
| void setBlendMode(BlendMode aBlendMode); |
| |
| /** |
| * Creates an image with a file. |
| * @param aFile Reference to a file. |
| * @return Initialized instance of VisualImage. NULL in case of failure. |
| * @remarks The caller has to release (delete) the allocated memory. |
| */ |
| static VisualImage* createWithFile(VisualFile& aFile); |
| |
| /** |
| * Creates an image with a buffer of ARGB pixel data. |
| * @param argbPixels Pointer to ARGB pixel data. |
| * @param width The width of the pixel data. |
| * @param height The height of the pixel data. |
| * @return Initialized instance of VisualImage. NULL in case of failure. |
| * @remarks The caller has to release (delete) the allocated memory. No reference to the pixel data is stored, pixel data can be savely disposed after the call. |
| */ |
| static VisualImage* createWithARGBPixelData(PixelColor* argbPixels, uint32 width, uint32 height); |
| |
| /** |
| * Creates an image with a data pointer to encoded image data. |
| * @param bufferData A pointer to the data. |
| * @param size The size of the data pointed to in bytes. |
| * @return Initialized instance of VisualImage. NULL in case of failure. |
| * @remarks The caller has to release (delete) the initialized image. |
| */ |
| static VisualImage* createWithEncodedData(const char* const bufferData, uint32 size); |
| |
| /** |
| * Creates an image with a styled string. |
| * @param styledString The styled string to convert into bitmap image. |
| * @return Initialized instance of VisualImage. NULL in case of failure. |
| * @remarks The caller has to release (delete) the allocated memory. |
| */ |
| static VisualImage* createWithStyledString(VisualStyledString& styledString); |
| |
| #if TARGET_OS_MAC |
| /** |
| * Creates an image with a resource image. |
| * @param name The name of the resource. |
| * @return Initialized instance of VisualImage. NULL in case of failure. |
| * @remarks The caller has to release (delete) the allocated memory. |
| */ |
| static VisualImage* createWithResource(const char* name); |
| #endif |
| #if TARGET_OS_WIN |
| /** |
| * Creates an image with a resource image. |
| * @param nameId The id of the resource. |
| * @return Initialized instance of VisualImage. NULL in case of failure. |
| * @remarks The caller has to release (delete) the allocated memory. |
| */ |
| static VisualImage* createWithResource(int nameId); |
| #endif |
| |
| /** |
| * Creates an image with an URL. |
| * @param anURL URL of the image. |
| * @param anId Identifier that can be queried to track the progress of this asynchronous creation. |
| * @return Initialized instance of VisualImage. |
| * @remarks The caller has to release (delete) the allocated memory. |
| */ |
| static VisualImage* createWithURL(VisualString& anURL, VisualItemIdentifier& anId); |
| |
| /** |
| * Creates an image with contents of the current screen (framebuffer). |
| * @param clipRect The dimensions and position of the clip rect. |
| * @remarks The caller has to release (delete) the allocated memory. |
| */ |
| static VisualImage* createWithFramebuffer(const BottomLeftPositionedPixelRect& clipRect); |
| |
| /** |
| * Resamples the pixel data of the texture to the given dimensions of the pixelRect. |
| * @param pixelRect The resampling dimensions. |
| */ |
| void resample(const PixelRect& pixelRect); |
| |
| /** |
| * Returns a pointer to the texture container of the image. |
| * @return A pointer to the texture container of the image. |
| */ |
| VisualTextureContainer* getTextureContainer(void) const; |
| |
| /** |
| * Notification that the loading of data ended. |
| * @param identifier The identifier of the data load request. |
| */ |
| virtual void dataLoadDidEnd(const VisualItemIdentifier& identifier); |
| |
| /** |
| * Creates a histogram of RGB pixel color values. A histogram contains the salient color values of the image. |
| * @remarks The histogram is created asynchronously. On finish, a notification is sent (kImageHistogramCompletedMsg) on which actors can be registered. The image is downsampled and the histogram is calculated with the k-means algorithm. |
| */ |
| void createHistogram(void); |
| |
| /** |
| * Returns the internal histogram. |
| * @return The histogram. Can be NULL in case no histogram has been set. |
| */ |
| VisualHistogram::PixelColorHistogram* getHistogram(void); |
| |
| private: |
| |
| /** |
| * Copy method for assignment operator and copy constructor. |
| * @param other Another VisualImage. |
| */ |
| void copy(const VisualImage& other); |
| |
| /** Pointer to the VisualTextureContainer. */ |
| VisualTextureContainer* visualTextureContainer; |
| |
| /** True if image has been set. False if image is not valid or has not been set yet. */ |
| bool isSet; |
| |
| /** The blend mode of the image. */ |
| BlendMode blendMode; |
| |
| /** |
| * Returns the array of RGB color pixels as required to create a histogram. |
| * @param[out] inputValues The pixels that can be used as input for histogram creation. |
| */ |
| void getRGBHistogramInputPixels(std::vector<PixelColor>& inputValues) const; |
| |
| /** |
| * Creates a histogram of RGB pixel color values. |
| * @param visualImageHistogramPixelColors Pixel color values and pointer to image. |
| */ |
| #if TARGET_OS_MAC |
| static OSStatus createHistogramOfRGBPixelsThread(void* visualImageHistogramPixelColors); |
| #endif |
| #if TARGET_OS_WIN |
| static DWORD createHistogramOfRGBPixelsThread(LPVOID visualImageHistogramPixelColors); |
| #endif |
| |
| /** Histogram. */ |
| VisualHistogram::PixelColorHistogram* histogram; |
| |
| /** |
| * Exchange data type for histogram creation. |
| */ |
| typedef struct { |
| std::vector<PixelColor> pixelColorValuesVector; /**< The RGB pixelcolor value. */ |
| VisualImage* visualImage; /**< Pointer to image. */ |
| } VisualImageHistogramPixelColors; |
| |
| }; |
| |
| } |
| |
| #endif /* VisualImage_h */ |