+ This is also useful for scaling bitmaps in general as the only other way
+ to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC.
+
+ The parameter @a quality determines what method to use for resampling the image.
+ Can be one of the following:
+ - wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of pixel
+ replication
+ - wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling methods
+ for upsampling and downsampling respectively
+
+ It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer
+ looking results it is a slower method. Downsampling will use the box averaging
+ method which seems to operate very fast. If you are upsampling larger images using
+ this method you will most likely notice that it is a bit slower and in extreme
+ cases it will be quite substantially slower as the bicubic algorithm has to process a
+ lot of data.
+
+ It should also be noted that the high quality scaling may not work as expected
+ when using a single mask colour for transparency, as the scaling will blur the
+ image and will therefore remove the mask partially. Using the alpha channel
+ will work.
+
+ Example:
+ @code
+ // get the bitmap from somewhere
+ wxBitmap bmp = ...;
+
+ // rescale it to have size of 32*32
+ if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
+ {
+ wxImage image = bmp.ConvertToImage();
+ bmp = wxBitmap(image.Scale(32, 32));
+
+ // another possibility:
+ image.Rescale(32, 32);
+ bmp = image;
+ }
+ @endcode
+
+ @see Rescale()
+ */
+ wxImage Scale(int width, int height,
+ int quality = wxIMAGE_QUALITY_NORMAL) const;
+
+ /**
+ Returns a resized version of this image without scaling it by adding either a
+ border with the given colour or cropping as necessary.
+
+ The image is pasted into a new image with the given @a size and background
+ colour at the position @a pos relative to the upper left of the new image.
+
+ If @a red = green = blue = -1 then the areas of the larger image not covered
+ by this image are made transparent by filling them with the image mask colour
+ (which will be allocated automatically if it isn't currently set).
+
+ Otherwise, the areas will be filled with the colour with the specified RGB components.
+
+ @see Resize()
+ */
+ wxImage Size(const wxSize& size, const wxPoint& pos, int red = -1,
+ int green = -1, int blue = -1) const;
+
+ //@}
+
+
+ /**
+ @name Conversion functions
+ */
+ //@{
+
+ /**
+ If the image has alpha channel, this method converts it to mask.
+
+ If the image has an alpha channel, all pixels with alpha value less
+ than @a threshold are replaced with the mask colour and the alpha
+ channel is removed. Otherwise nothing is done.
+
+ The mask colour is chosen automatically using
+ FindFirstUnusedColour() by this function, see the overload below if you
+ this is not appropriate.
+
+ @return @false if FindFirstUnusedColour returns @false, @true otherwise.
+ */
+ bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
+
+ /**
+ If the image has alpha channel, this method converts it to mask using
+ the specified colour as the mask colour.
+
+ If the image has an alpha channel, all pixels with alpha value less
+ than @a threshold are replaced with the mask colour and the alpha
+ channel is removed. Otherwise nothing is done.
+
+ @since 2.9.0
+
+ @param mr
+ The red component of the mask colour.
+ @param mg
+ The green component of the mask colour.
+ @param mb
+ The blue component of the mask colour.
+ @param threshold
+ Pixels with alpha channel values below the given threshold are
+ considered to be transparent, i.e. the corresponding mask pixels
+ are set. Pixels with the alpha values above the threshold are
+ considered to be opaque.
+
+ */
+ void ConvertAlphaToMask(unsigned char mr, unsigned char mg, unsigned char mb,
+ unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
+
+ /**
+ Returns a greyscale version of the image.
+
+ The returned image uses the luminance component of the original to
+ calculate the greyscale. Defaults to using the standard ITU-T BT.601
+ when converting to YUV, where every pixel equals
+ (R * @a lr) + (G * @a lg) + (B * @a lb).
+ */
+ wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.114) const;
+
+ /**
+ Returns monochromatic version of the image.
+
+ The returned image has white colour where the original has @e (r,g,b)
+ colour and black colour everywhere else.
+ */
+ wxImage ConvertToMono(unsigned char r, unsigned char g, unsigned char b) const;
+
+ //@}
+
+
+ /**
+ @name Miscellaneous functions
+ */
+ //@{
+
+ /**
+ Computes the histogram of the image. @a histogram is a reference to
+ wxImageHistogram object. wxImageHistogram is a specialization of
+ wxHashMap "template" and is defined as follows:
+
+ @code
+ class WXDLLEXPORT wxImageHistogramEntry
+ {
+ public:
+ wxImageHistogramEntry() : index(0), value(0) {}
+ unsigned long index;
+ unsigned long value;
+ };
+
+ WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
+ wxIntegerHash, wxIntegerEqual,
+ wxImageHistogram);
+ @endcode
+
+ @return Returns number of colours in the histogram.
+ */
+ unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
+
+ /**
+ Finds the first colour that is never used in the image.
+ The search begins at given initial colour and continues by increasing
+ R, G and B components (in this order) by 1 until an unused colour is
+ found or the colour space exhausted.
+
+ The parameters @a r, @a g, @a b are pointers to variables to save the colour.
+
+ The parameters @a startR, @a startG, @a startB define the initial values
+ of the colour.
+ The returned colour will have RGB values equal to or greater than these.
+
+ @return Returns @false if there is no unused colour left, @true on success.
+
+ @note
+ This method involves computing the histogram, which is a
+ computationally intensive operation.
+ */
+ bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
+ unsigned char* b, unsigned char startR = 1,
+ unsigned char startG = 0,
+ unsigned char startB = 0) const;
+
+ /**
+ Assignment operator, using @ref overview_refcount "reference counting".
+
+ @param image
+ Image to assign.
+
+ @return Returns 'this' object.
+ */
+ wxImage& operator=(const wxImage& image);
+
+ //@}
+
+
+ /**
+ @name Getters
+ */
+ //@{
+
+ /**
+ Returns pointer to the array storing the alpha values for this image.
+
+ This pointer is @NULL for the images without the alpha channel. If the image
+ does have it, this pointer may be used to directly manipulate the alpha values
+ which are stored as the RGB ones.
+ */
+ unsigned char* GetAlpha() const;
+
+ /**
+ Returns the image data as an array.
projects / wxWidgets.git / blobdiff