X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1e6d94998fcbdb3ce60774e38c0d4b6ee20c6798..6cf7c00f3beb3aa6c84b47d43d904e0e40f91a97:/docs/latex/wx/image.tex diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex index 6eac4c09cd..8325f4be63 100644 --- a/docs/latex/wx/image.tex +++ b/docs/latex/wx/image.tex @@ -7,12 +7,17 @@ via image format handlers. Functions are available to set and get image bits, so it can be used for basic image manipulation. A wxImage cannot (currently) be drawn directly to a wxDC. Instead, a platform-specific -wxBitmap object must be created from it, and that bitmap drawn on the wxDC. +wxBitmap object must be created from it, and that bitmap drawn on the wxDC, using +wxDC::DrawBitmap. \wxheading{Derived from} \helpref{wxObject}{wxobject} +\wxheading{Include files} + + + \wxheading{See also} \helpref{wxBitmap}{wxbitmap} @@ -31,7 +36,9 @@ Copy constructor. \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}} -Constructs an image from a platform-dependent bitmap. +Constructs an image from a platform-dependent bitmap. This preserves +mask information so that bitmaps and images can be converted back +and forth without loss in that respect. \func{}{wxImage}{\param{int}{ width}, \param{int}{ height}} @@ -39,8 +46,16 @@ Creates an image with the given width and height. \func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}} +\func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}} + Loads an image from a file. +\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}} + +\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}} + +Loads an image from an input stream. + \wxheading{Parameters} \docparam{width}{Specifies the width of the image.} @@ -49,20 +64,26 @@ Loads an image from a file. \docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.} +\docparam{stream}{This refers to an input stream. Its meaning is determined by the {\it type} parameter. It is equal to loading from file except that you provide opened stream (file, HTTP or any other custom class).} + \docparam{type}{May be one of the following: -\twocolwidtha{5cm} +\twocolwidtha{5cm}% \begin{twocollist} \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.} -\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.} -\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XBM}}}{Load an X bitmap file.} -\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XPM}}}{Load an XPM bitmap file.} \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.} +\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_JPEG}}}{Load a JPEG bitmap file.} \end{twocollist} The validity of these flags depends on the platform and wxWindows configuration. -If all possible wxWindows settings are used, the Windows platform supports BMP, BMP\_RESOURCE, -XPM\_DATA, and XPM. Under X, the available formats are BMP, GIF, XBM, and XPM.} +If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file, +a PNG (portable network graphics) file and a JPEG file is supported on all platforms that +implement wxImage.} + +\docparam{mimetype}{MIME type string (for example 'image/jpeg')} + +Note : you must call wxImage::AddHandler(new wxJPEGHandler) during application +initialization in order to work with JPEGs. \wxheading{See also} @@ -99,7 +120,12 @@ This function is called by wxWindows on exit. \constfunc{wxBitmap}{ConvertToBitmap}{\void} -Converts the image to a platform-specific bitmap object. +Converts the image to a platform-specific bitmap object. This has to be done +to actually display an image as you cannot draw an image directly on a window. +The resulting bitmap will use the colour depth of the current system which entails +that a (crude) colour reduction has to take place. When in 8-bit mode, this +routine will use a color cube created on program start-up to look up colors. +Still, the image quality won't be perfect for photo images. \membersection{wxImage::Create}\label{wximagecreate} @@ -137,12 +163,18 @@ Finds the handler associated with the given extension and type. Finds the handler associated with the given image type. +\func{static wxImageHandler*}{FindHandlerMime}{\param{const wxString\& }{mimetype}} + +Finds the handler associated with the given MIME type. + \docparam{name}{The handler name.} \docparam{extension}{The file extension, such as ``bmp".} \docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.} +\docparam{mimetype}{MIME type.} + \wxheading{Return value} A pointer to the handler if found, NULL otherwise. @@ -161,7 +193,9 @@ Returns the blue intensity at the given coordinate. \constfunc{unsigned char*}{GetData}{\void} -Returns the image data as an array. +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 +chararcters in RGBGBRGB... format. \membersection{wxImage::GetGreen}\label{wximagegetgreen} @@ -230,7 +264,8 @@ Returns TRUE if there is a mask active, FALSE otherwise. \func{static void}{InitStandardHandlers}{\void} Adds the standard image format handlers, which, depending on wxWindows -configuration, can be handlers for Windows image, Windows image resource, and XPM. +configuration, can be handlers for Windows BMP (loading), PNG +(loading and saving) and JPEG (loading and saving) file formats. This function is called by wxWindows on startup. @@ -255,26 +290,37 @@ of a given handler class in an application session.} \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}} +\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}} + Loads an image from a file. +\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}} + +\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}} + +Loads an image from an input stream. + \wxheading{Parameters} \docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.} +\docparam{stream}{An input stream. +The meaning of {\it stream} data is determined by the {\it type} parameter.} + \docparam{type}{One of the following values: -\twocolwidtha{5cm} +\twocolwidtha{5cm}% \begin{twocollist} \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.} -\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF image file.} -\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Load an X image file.} -\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.} +\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.} \end{twocollist} The validity of these flags depends on the platform and wxWindows configuration.} +\docparam{mimetype}{MIME type string (for example 'image/jpeg')} + \wxheading{Return value} TRUE if the operation succeeded, FALSE otherwise. @@ -310,24 +356,34 @@ TRUE if the handler was found and removed, FALSE otherwise. \func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}} +\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}} + Saves a image in the named file. +\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}} + +\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}} + +Saves a image in the given stream. + \wxheading{Parameters} \docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.} -\docparam{type}{One of the following values: +\docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.} + +\docparam{type}{Currently two types can be used: -\twocolwidtha{5cm} +\twocolwidtha{5cm}% \begin{twocollist} -\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Save a Windows image file.} -\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Save a GIF image file.} -\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Save an X image file.} -\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.} +\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.} \end{twocollist} -The validity of these flags depends on the platform and wxWindows configuration.} +The validity of these flags depends on the platform and wxWindows configuration +as well as user-added handlers.} + +\docparam{mimetype}{MIME type.} \wxheading{Return value} @@ -345,13 +401,19 @@ Depending on how wxWindows has been configured, not all formats may be available \func{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}} -Returns a scaled version of the image. +Returns a scaled version of the image. 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. Windows can do such +scaling itself but in the GTK port, scaling bitmaps is done using +this routine internally. \membersection{wxImage::SetData}\label{wximagesetdata} \func{void}{SetData}{\param{unsigned char*}{data}} -Sets the image data. +Sets the image data without performing checks. The data given must have +the size (width*height*3) or results will be unexpected. Don't use this +method if you aren't sure you know what you are doing. \membersection{wxImage::SetMask}\label{wximagesetmask} @@ -363,13 +425,16 @@ Specifies whether there is a mask or not. The area of the mask is determined by \func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}} -Sets the mask colour for this image. +Sets the mask colour for this image (and tells the image to use the mask). \membersection{wxImage::SetRGB}\label{wximagesetrgb} \func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}} -Sets the pixel at the given coordinate. +Sets the pixel at the given coordinate. This routine performs bounds-checks +for the coordinate so it can be considered a safe way to manipulate the +data, but in some cases this might be too slow so that the data will have to +be set directly. In that case you have to get that data by calling GetData(). \membersection{wxImage::operator $=$} @@ -419,8 +484,6 @@ Returns TRUE if the images were unequal, FALSE otherwise. \section{\class{wxImageHandler}}\label{wximagehandler} -\overview{Overview}{wximageoverview} - This is the base class for implementing image file loading/saving, and image creation from data. It is used within wxImage and is not normally seen by the application. @@ -428,10 +491,21 @@ If you wish to extend the capabilities of wxImage, derive a class from wxImageHa and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your application initialisation. +\wxheading{Note (Legal Issue)} + +This software is based in part on the work of the Independent JPEG Group. + +(Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg +created by IJG.) + \wxheading{Derived from} \helpref{wxObject}{wxobject} +\wxheading{Include files} + + + \wxheading{See also} \helpref{wxImage}{wximage} @@ -469,18 +543,24 @@ Gets the file extension associated with this handler. Gets the image type associated with this handler. +\membersection{wxImageHandler::GetMimeType} + +\constfunc{wxString}{GetMimeType}{\void} + +Gets the MIME type associated with this handler. + \membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile} -\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{const wxString\&}{ name}} +\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}} -Loads a image from a file or resource, putting the resulting data into {\it image}. +Loads a image from a stream, putting the resulting data into {\it image}. \wxheading{Parameters} \docparam{image}{The image object which is to be affected by this operation.} -\docparam{name}{Either a filename or a Windows resource name. -The meaning of {\it name} is determined by the {\it type} parameter.} +\docparam{stream}{Opened input stream. +The meaning of {\it stream} is determined by the {\it type} parameter.} \wxheading{Return value} @@ -494,15 +574,15 @@ TRUE if the operation succeeded, FALSE otherwise. \membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile} -\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{const wxString\& }{name}} +\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}} -Saves a image in the named file. +Saves a image in the output stream. \wxheading{Parameters} \docparam{image}{The image object which is to be affected by this operation.} -\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.} +\docparam{stream}{A stream. The meaning of {\it stream} is determined by the {\it type} parameter.} \wxheading{Return value} @@ -545,3 +625,13 @@ Sets the handler type. \docparam{name}{Handler type.} +\membersection{wxImageHandler::SetMimeType} + +\func{void}{SetMimeType}{\param{const wxString\& }{mimetype}} + +Sets the handler MIME type. + +\wxheading{Parameters} + +\docparam{mimename}{Handler MIME type.} +