X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8727a1fe6f530b33829384c052484238c5e06e54..302a1ecae3fceff78222f85eb0b9052e845083d2:/docs/latex/wx/image.tex diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex index 26c445a4da..ee616abdb3 100644 --- a/docs/latex/wx/image.tex +++ b/docs/latex/wx/image.tex @@ -18,17 +18,18 @@ creation of a \helpref{wxMask}{wxmask} object associated to the bitmap object. The following image handlers are available. {\bf wxBMPHandler} is always installed by default. To use other image formats, install the appropiate -handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or +handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}. \twocolwidtha{5cm}% \begin{twocollist} -\twocolitem{{\bf \indexit{wxBMPHandler}}}{Only for loading, always installed.} -\twocolitem{{\bf \indexit{wxPNGHandler}}}{For loading and saving.} -\twocolitem{{\bf \indexit{wxJPEGHandler}}}{For loading and saving.} -\twocolitem{{\bf \indexit{wxGIFHandler}}}{Only for loading, due to legal issues.} -\twocolitem{{\bf \indexit{wxPCXHandler}}}{For loading and saving (see below).} -\twocolitem{{\bf \indexit{wxPNMHandler}}}{For loading and saving (see below).} +\twocolitem{\indexit{wxBMPHandler}}{Only for loading, always installed.} +\twocolitem{\indexit{wxPNGHandler}}{For loading and saving.} +\twocolitem{\indexit{wxJPEGHandler}}{For loading and saving.} +\twocolitem{\indexit{wxGIFHandler}}{Only for loading, due to legal issues.} +\twocolitem{\indexit{wxPCXHandler}}{For loading and saving (see below).} +\twocolitem{\indexit{wxPNMHandler}}{For loading and saving (see below).} +\twocolitem{\indexit{wxTIFFHandler}}{For loading.} \end{twocollist} When saving in PCX format, {\bf wxPCXHandler} will count the number of @@ -48,7 +49,7 @@ PNM format, {\bf wxPNMHandler} will always save as raw RGB. \wxheading{See also} -\helpref{wxBitmap}{wxbitmap} +\helpref{wxBitmap}{wxbitmap}, \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers} \latexignore{\rtfignore{\wxheading{Members}}} @@ -73,13 +74,20 @@ and forth without loss in that respect. Creates an image with the given width and height. -\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}} +\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{unsigned char*}{ data}, \param{bool}{ static_data=FALSE}} + +Creates an image from given data with the given width and height. If +{\it static_data} is TRUE, then wxImage will not delete the actual +image data in its destructor, otherwise it will free it by calling +{\it free()}. + +\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}} \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{long}{ type = wxBITMAP\_TYPE\_ANY}} \func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}} @@ -91,31 +99,33 @@ Loads an image from an input stream. \docparam{height}{Specifies the height of the image.} -\docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.} +\docparam{name}{Name of the file from which to load the image.} -\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{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.} \docparam{type}{May be one of the following: \twocolwidtha{5cm}% \begin{twocollist} -\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.} -\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.} -\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_JPEG}}}{Load a JPEG bitmap file.} -\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.} -\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PCX}}}{Load a PCX bitmap file.} -\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNM}}}{Load a PNM bitmap file.} -\end{twocollist} - -The validity of these flags depends on the platform and wxWindows configuration. -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.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.} +\end{twocollist}} \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{Remarks} + +Depending on how wxWindows has been configured, not all formats may be available. + +Note: any handler other than BMP must be previously +initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or +\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}. \wxheading{See also} @@ -135,6 +145,15 @@ platform-dependent bitmap} \end{twocollist}} } +\perlnote{Constructors supported by wxPerl are:\par +\begin{itemize} +\item{Wx::Image->new( bitmap )} +\item{Wx::Image->new( width, height )} +\item{Wx::Image->new( name, type )} +\item{Wx::Image->new( name, mimetype )} +\end{itemize} +} + \membersection{wxImage::\destruct{wxImage}} \func{}{\destruct{wxImage}}{\void} @@ -177,6 +196,16 @@ on program start-up to look up colors. This ensures a very fast conversion, but the image quality won't be perfect (and could be better for photo images using more sophisticated dithering algorithms). +On Windows, if there is a palette present (set with SetPalette), it will be used when +creating the wxBitmap (most useful in 8-bit display mode). On other platforms, +the palette is currently ignored. + +\membersection{wxImage::Copy}\label{wximagecopy} + +\constfunc{wxImage}{Copy}{\void} + +Returns an identical copy of the image. + \membersection{wxImage::Create}\label{wximagecreate} \func{bool}{Create}{\param{int}{ width}, \param{int}{ height}} @@ -293,6 +322,15 @@ Gets the green value of the mask colour. Gets the red value of the mask colour. +\membersection{wxImage::GetPalette}\label{wximagegetpalette} + +\constfunc{const wxPalette\&}{GetPalette}{\void} + +Returns the palette associated with the image. Currently the palette is only +used in ConvertToBitmap under Windows. + +Eventually wxImage handlers will set the palette if one exists in the image file. + \membersection{wxImage::GetSubImage}\label{wximagegetsubimage} \constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}} @@ -316,19 +354,58 @@ Gets the width of the image in pixels. Returns TRUE if there is a mask active, FALSE otherwise. +\membersection{wxImage::GetOption}\label{wximagegetoption} + +\constfunc{wxString}{GetOption}{\param{const wxString\&}{ name}} + +Gets a user-defined option. The function is case-insensitive to {\it name}. + +For example, when saving as a JPEG file, the option {\bf quality} is +used, which is a number between 0 and 100 (0 is terrible, 100 is very good). + +\wxheading{See also} + +\helpref{wxImage::SetOption}{wximagesetoption},\rtfsp +\helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp +\helpref{wxImage::HasOption}{wximagehasoption} + +\membersection{wxImage::GetOptionInt}\label{wximagegetoptionint} + +\constfunc{int}{GetOptionInt}{\param{const wxString\&}{ name}} + +Gets a user-defined option as an integer. The function is case-insensitive to {\it name}. + +\wxheading{See also} + +\helpref{wxImage::SetOption}{wximagesetoption},\rtfsp +\helpref{wxImage::GetOption}{wximagegetoption},\rtfsp +\helpref{wxImage::HasOption}{wximagehasoption} + +\membersection{wxImage::HasOption}\label{wximagehasoption} + +\constfunc{bool}{HasOption}{\param{const wxString\&}{ name}} + +Returns TRUE if the given option is present. The function is case-insensitive to {\it name}. + +\wxheading{See also} + +\helpref{wxImage::SetOption}{wximagesetoption},\rtfsp +\helpref{wxImage::GetOption}{wximagegetoption},\rtfsp +\helpref{wxImage::GetOptionInt}{wximagegetoptionint} + \membersection{wxImage::InitStandardHandlers} \func{static void}{InitStandardHandlers}{\void} Internal use only. Adds standard image format handlers. It only install BMP -for the time being, which is use by wxBitmap. +for the time being, which is used by wxBitmap. This function is called by wxWindows on startup, and shouldn't be called by the user. \wxheading{See also} -\helpref{wxImageHandler}{wximagehandler} +\helpref{wxImageHandler}{wximagehandler}, \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers} \membersection{wxImage::InsertHandler} @@ -351,7 +428,7 @@ of a given handler class in an application session.} \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}} Loads an image from a file. If no handler type is provided, the library will -try to use wxBITMAP\_TYPE\_BMP. +try to autodetect the format. \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}} @@ -361,11 +438,9 @@ 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{name}{Name of the file from which to load the image.} -\docparam{stream}{An input stream. -The meaning of {\it stream} data is determined by the {\it type} parameter.} +\docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.} \docparam{type}{One of the following values: @@ -373,17 +448,20 @@ The meaning of {\it stream} data is determined by the {\it type} parameter.} \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\_TIF}}{Load a TIFF image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Load a PCX image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.} -\end{twocollist} - -The validity of these flags depends on the platform and wxWindows configuration.} +\twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.} +\twocolitem{{\bf wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.} +\end{twocollist}} \docparam{mimetype}{MIME type string (for example 'image/jpeg')} +\wxheading{Remarks} + +Depending on how wxWindows has been configured, not all formats may be available. + \wxheading{Return value} TRUE if the operation succeeded, FALSE otherwise. @@ -402,6 +480,13 @@ mimetype from a file} \end{twocollist}} } +\perlnote{Methods supported by wxPerl are:\par +\begin{itemize} +\item{bitmap->LoadFile( name, type )} +\item{bitmap->LoadFile( name, mimetype )} +\end{itemize} +} + \membersection{wxImage::Ok}\label{wximageok} @@ -442,21 +527,19 @@ 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{name}{Name of the file to save the image to.} -\docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.} +\docparam{stream}{Opened output stream to save the image to.} \docparam{type}{Currently three types can be used: \twocolwidtha{5cm}% \begin{twocollist} -\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.} -\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file.} -\end{twocollist} - -The validity of these flags depends on the platform and wxWindows configuration -as well as user-added handlers.} +\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.} +\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise).} +\twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).} +\end{twocollist}} \docparam{mimetype}{MIME type.} @@ -482,6 +565,20 @@ mimetype to the named file} \end{twocollist}} } +\perlnote{Methods supported by wxPerl are:\par +\begin{itemize} +\item{bitmap->SaveFile( name, type )} +\item{bitmap->SaveFile( name, mimetype )} +\end{itemize} +} + +\membersection{wxImage::Mirror}\label{wximagemirror} + +\constfunc{wxImage}{Mirror}{\param{bool}{ horizontally = TRUE}} + +Returns a mirrored copy of the image. The parameter {\it horizontally} +indicates the orientation. + \membersection{wxImage::Replace}\label{wximagereplace} \func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1}, @@ -502,6 +599,25 @@ Returns the (modified) image itself. \helpref{Scale}{wximagescale} +\membersection{wxImage::Rotate}\label{wximagerotate} + +\func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre}, + \param{bool}{ interpolating = TRUE}, \param{wxPoint*}{ offsetAfterRotation = NULL}} + +Rotates the image about the given point, by {\it angle} radians. Passing TRUE +to {\it interpolating} results in better image quality, but is slower. If the +image has a mask, then the mask colour is used for the uncovered pixels in the +rotated image background. Else, black (rgb 0, 0, 0) will be used. + +Returns the rotated image, leaving this image intact. + +\membersection{wxImage::Rotate90}\label{wximagerotate90} + +\constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = TRUE}} + +Returns a copy of the image rotated 90 degrees in the direction +indicated by {\it clockwise}. + \membersection{wxImage::Scale}\label{wximagescale} \constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}} @@ -511,7 +627,7 @@ scaling bitmaps in general as the only other way to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC. It may be mentioned that the GTK port uses this function internally -to scale bitmaps when using mapping mode in wxDC. +to scale bitmaps when using mapping modes in wxDC. Example: @@ -556,9 +672,33 @@ Specifies whether there is a mask or not. The area of the mask is determined by Sets the mask colour for this image (and tells the image to use the mask). +\membersection{wxImage::SetOption}\label{wximagesetoption} + +\func{void}{SetOption}{\param{const wxString\&}{ name}, \param{const wxString\&}{ value}} + +\func{void}{SetOption}{\param{const wxString\&}{ name}, \param{int}{ value}} + +Sets a user-defined option. The function is case-insensitive to {\it name}. + +For example, when saving as a JPEG file, the option {\bf quality} is +used, which is a number between 0 and 100 (0 is terrible, 100 is very good). + +\wxheading{See also} + +\helpref{wxImage::GetOption}{wximagegetoption},\rtfsp +\helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp +\helpref{wxImage::HasOption}{wximagehasoption} + +\membersection{wxImage::SetPalette}\label{wximagesetpalette} + +\func{void}{SetPalette}{\param{const wxPalette\&}{ palette}} + +Associates a palette with the image. The palette may be used in ConvertToBitmap (MSW only at present) +or in file save operations (none as yet). + \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}} +\func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}} 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 @@ -638,7 +778,7 @@ created by IJG.) \wxheading{See also} -\helpref{wxImage}{wximage} +\helpref{wxImage}{wximage}, \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers} \latexignore{\rtfignore{\wxheading{Members}}} @@ -676,7 +816,7 @@ If the image file contains more than one image and the image handler is capable of retrieving these individually, this function will return the number of available images. -\docparam{stream}{Opened input stream for reading image file.} +\docparam{stream}{Opened input stream for reading image data. Currently, the stream must support seeking.} \wxheading{Return value} @@ -706,7 +846,7 @@ indicates which image to read from the stream. \docparam{image}{The image object which is to be affected by this operation.} -\docparam{stream}{Opened input stream for reading images.} +\docparam{stream}{Opened input stream for reading image data.} \docparam{verbose}{If set to TRUE, errors reported by the image handler will produce wxLogMessages.} @@ -718,8 +858,8 @@ TRUE if the operation succeeded, FALSE otherwise. \wxheading{See also} -\helpref{wxImage::LoadFile}{wximageloadfile}\\ -\helpref{wxImage::SaveFile}{wximagesavefile}\\ +\helpref{wxImage::LoadFile}{wximageloadfile}, +\helpref{wxImage::SaveFile}{wximagesavefile}, \helpref{wxImageHandler::SaveFile}{wximagehandlersavefile} \membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile} @@ -732,7 +872,7 @@ Saves a image in the output stream. \docparam{image}{The image object which is to be affected by this operation.} -\docparam{stream}{An opened stream for writing images.} +\docparam{stream}{Opened output stream for writing the data.} \wxheading{Return value} @@ -740,8 +880,8 @@ TRUE if the operation succeeded, FALSE otherwise. \wxheading{See also} -\helpref{wxImage::LoadFile}{wximageloadfile}\\ -\helpref{wxImage::SaveFile}{wximagesavefile}\\ +\helpref{wxImage::LoadFile}{wximageloadfile}, +\helpref{wxImage::SaveFile}{wximagesavefile}, \helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile} \membersection{wxImageHandler::SetName} @@ -764,24 +904,23 @@ Sets the handler extension. \docparam{extension}{Handler extension.} -\membersection{wxImageHandler::SetType} +\membersection{wxImageHandler::SetMimeType}\label{wximagehandlersetmimetype} -\func{void}{SetType}{\param{long }{type}} +\func{void}{SetMimeType}{\param{const wxString\& }{mimetype}} -Sets the handler type. +Sets the handler MIME type. \wxheading{Parameters} -\docparam{name}{Handler type.} - +\docparam{mimename}{Handler MIME type.} -\membersection{wxImageHandler::SetMimeType} +\membersection{wxImageHandler::SetType} -\func{void}{SetMimeType}{\param{const wxString\& }{mimetype}} +\func{void}{SetType}{\param{long }{type}} -Sets the handler MIME type. +Sets the handler type. \wxheading{Parameters} -\docparam{mimename}{Handler MIME type.} +\docparam{name}{Handler type.}