+ 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.
+
+ This is most often used when doing direct image manipulation.
+ The return value points to an array of characters in RGBRGBRGB... format
+ in the top-to-bottom, left-to-right order, that is the first RGB triplet
+ corresponds to the pixel first pixel of the first row, the second one ---
+ to the second pixel of the first row and so on until the end of the first
+ row, with second row following after it and so on.
+
+ You should not delete the returned pointer nor pass it to SetData().
projects / wxWidgets.git / blobdiff