X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ccec90930cfc38bd4347a97f46481242d9fd23cd..403695b3236ce0ccca5ba7493736926566c9addc:/interface/wx/image.h diff --git a/interface/wx/image.h b/interface/wx/image.h index 5efb33a5d6..34808c5c15 100644 --- a/interface/wx/image.h +++ b/interface/wx/image.h @@ -39,10 +39,25 @@ enum wxImageResizeQuality /// Highest quality but slowest execution time. wxIMAGE_QUALITY_BICUBIC, - /// Default image resizing algorithm used by wxImage::Scale(). + /** + Use surrounding pixels to calculate an average that will be used for + new pixels. This method is typically used when reducing the size of + an image. + */ + wxIMAGE_QUALITY_BOX_AVERAGE, + + /** + Default image resizing algorithm used by wxImage::Scale(). Currently + the same as wxIMAGE_QUALITY_NEAREST. + */ wxIMAGE_QUALITY_NORMAL, - /// Best image resizing algorithm, currently same as wxIMAGE_QUALITY_BICUBIC. + /** + Best image resizing algorithm. Since version 2.9.2 this results in + wxIMAGE_QUALITY_BOX_AVERAGE being used when reducing the size of the + image (meaning that both the new width and height will be smaller than + the original size). Otherwise wxIMAGE_QUALITY_BICUBIC is used. + */ wxIMAGE_QUALITY_HIGH }; @@ -55,7 +70,8 @@ enum wxImagePNGType { wxPNG_TYPE_COLOUR = 0, ///< Colour PNG image. wxPNG_TYPE_GREY = 2, ///< Greyscale PNG image converted from RGB. - wxPNG_TYPE_GREY_RED = 3 ///< Greyscale PNG image using red as grey. + wxPNG_TYPE_GREY_RED = 3, ///< Greyscale PNG image using red as grey. + wxPNG_TYPE_PALETTE = 4 ///< Palette encoding. }; /** @@ -315,10 +331,12 @@ const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff; While all images have RGB data, not all images have an alpha channel. Before using wxImage::GetAlpha you should check if this image contains an alpha - channel with wxImage::HasAlpha. Note that currently only the PNG format has - full alpha channel support so only the images loaded from PNG files can have - alpha and, if you initialize the image alpha channel yourself using - wxImage::SetAlpha, you should save it in PNG format to avoid losing it. + channel with wxImage::HasAlpha. Currently the BMP, PNG, and TIFF format + handlers have full alpha channel support for loading so if you want to use + alpha you have to use one of these formats. If you initialize the image + alpha channel yourself using wxImage::SetAlpha, you should save it in + either PNG or TGA format to avoid losing it as these are the only handlers + that currently support saving with alpha. @section image_handlers Available image handlers @@ -328,14 +346,14 @@ const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff; To use other image formats, install the appropriate handler with wxImage::AddHandler or call ::wxInitAllImageHandlers(). - - wxBMPHandler: For loading and saving, always installed. - - wxPNGHandler: For loading (including alpha support) and saving. + - wxBMPHandler: For loading (including alpha support) and saving, always installed. + - wxPNGHandler: For loading and saving. Includes alpha support. - wxJPEGHandler: For loading and saving. - - wxGIFHandler: Only for loading, due to legal issues. + - wxGIFHandler: For loading and saving (see below). - wxPCXHandler: For loading and saving (see below). - wxPNMHandler: For loading and saving (see below). - - wxTIFFHandler: For loading and saving. - - wxTGAHandler: For loading only. + - wxTIFFHandler: For loading (including alpha support) and saving. + - wxTGAHandler: For loading and saving. Includes alpha support. - wxIFFHandler: For loading only. - wxXPMHandler: For loading and saving. - wxICOHandler: For loading and saving. @@ -349,6 +367,8 @@ const unsigned char wxIMAGE_ALPHA_OPAQUE = 0xff; Loading PNMs only works for ASCII or raw RGB images. When saving in PNM format, wxPNMHandler will always save as raw RGB. + Saving GIFs requires images of maximum 8 bpp (see wxQuantize), and the alpha channel converted to a mask (see wxImage::ConvertAlphaToMask). + Saving an animated GIF requires images of the same size (see wxGIFHandler::SaveAnimation) @library{wxcore} @category{gdi} @@ -1072,7 +1092,7 @@ public: The function is case-insensitive to @a name. If the given option is not present, the function returns 0. - Use HasOption() is 0 is a possibly valid value for the option. + Use HasOption() if 0 is a possibly valid value for the option. Generic options: @li @c wxIMAGE_OPTION_MAX_WIDTH and @c wxIMAGE_OPTION_MAX_HEIGHT: If either @@ -1131,6 +1151,12 @@ public: the resulting PNG file. Use this option if your application produces images with small size variation. + Options specific to wxGIFHandler: + @li @c wxIMAGE_OPTION_GIF_COMMENT: The comment text that is read from + or written to the GIF file. In an animated GIF each frame can have + its own comment. If there is only a comment in the first frame of + a GIF it will not be repeated in other frames. + @param name The name of the option, case-insensitive. @return @@ -1556,7 +1582,19 @@ public: /** Register an image handler. - See @ref image_handlers for a list of the available handlers. + + Typical example of use: + @code + wxImage::AddHandler(new wxPNGHandler); + @endcode + + See @ref image_handlers for a list of the available handlers. You can + also use ::wxInitAllImageHandlers() to add handlers for all the image + formats supported by wxWidgets at once. + + @param handler + A heap-allocated handler object which will be deleted by wxImage + if it is removed later by RemoveHandler() or at program shutdown. */ static void AddHandler(wxImageHandler* handler); @@ -1648,7 +1686,8 @@ public: /** Finds the handler with the given name, and removes it. - The handler is not deleted. + + The handler is also deleted. @param name The handler name. @@ -1760,9 +1799,14 @@ wxImage wxNullImage; //@{ /** - Initializes all available image handlers. For a list of available handlers, - see wxImage. - If you don't need/want all image handlers loaded + Initializes all available image handlers. + + This function calls wxImage::AddHandler() for all the available image + handlers (see @ref image_handlers for the full list). Calling it is the + simplest way to initialize wxImage but it creates and registers even the + handlers your program may not use. If you want to avoid the overhead of + doing this you need to call wxImage::AddHandler() manually just for the + handlers that you do want to use. @see wxImage, wxImageHandler