docs/latex/wx/image.tex

   1 \section{\class{wxImage}}\label{wximage}
   2
   3 This class encapsulates a platform-independent image. An image can be created
   4 from data, or using the constructor taking a wxBitmap object. An image
   5 can be loaded from a file in a variety of formats, and is extensible to new formats
   6 via image format handlers. Functions are available to set and get image bits, so
   7 it can be used for basic image manipulation.
   8
   9 A wxImage cannot (currently) be drawn directly to a wxDC. Instead, a platform-specific
  10 wxBitmap object must be created from it, and that bitmap drawn on the wxDC, using
  11 wxDC::DrawBitmap.
  12
  13 \wxheading{Derived from}
  14
  15 \helpref{wxObject}{wxobject}
  16
  17 \wxheading{See also}
  18
  19 \helpref{wxBitmap}{wxbitmap}
  20
  21 \latexignore{\rtfignore{\wxheading{Members}}}
  22
  23 \membersection{wxImage::wxImage}\label{wximageconstr}
  24
  25 \func{}{wxImage}{\void}
  26
  27 Default constructor.
  28
  29 \func{}{wxImage}{\param{const wxImage\& }{image}}
  30
  31 Copy constructor.
  32
  33 \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
  34
  35 Constructs an image from a platform-dependent bitmap. This preserves
  36 mask information so that bitmaps and images can be converted back
  37 and forth without loss in that respect.
  38
  39 \func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}
  40
  41 Creates an image with the given width and height.
  42
  43 \func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
  44
  45 Loads an image from a file.
  46
  47 \func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
  48
  49 Loads an image from an input stream.
  50
  51 \wxheading{Parameters}
  52
  53 \docparam{width}{Specifies the width of the image.}
  54
  55 \docparam{height}{Specifies the height of the image.}
  56
  57 \docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.}
  58
  59 \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).}
  60
  61 \docparam{type}{May be one of the following:
  62
  63 \twocolwidtha{5cm}%
  64 \begin{twocollist}
  65 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.}
  66 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.}
  67 \twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_JPEG}}}{Load a JPEG bitmap file.}
  68 \end{twocollist}
  69
  70 The validity of these flags depends on the platform and wxWindows configuration.
  71 If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file,
  72 a PNG (portable network graphics) file and a JPEG file is supported on all platforms that
  73 implement wxImage.}
  74
  75 \wxheading{See also}
  76
  77 \helpref{wxImage::LoadFile}{wximageloadfile}
  78
  79 \membersection{wxImage::\destruct{wxImage}}
  80
  81 \func{}{\destruct{wxImage}}{\void}
  82
  83 Destructor.
  84
  85 \membersection{wxImage::AddHandler}\label{wximageaddhandler}
  86
  87 \func{static void}{AddHandler}{\param{wxImageHandler*}{ handler}}
  88
  89 Adds a handler to the end of the static list of format handlers.
  90
  91 \docparam{handler}{A new image format handler object. There is usually only one instance
  92 of a given handler class in an application session.}
  93
  94 \wxheading{See also}
  95
  96 \helpref{wxImageHandler}{wximagehandler}
  97
  98 \membersection{wxImage::CleanUpHandlers}
  99
 100 \func{static void}{CleanUpHandlers}{\void}
 101
 102 Deletes all image handlers.
 103
 104 This function is called by wxWindows on exit.
 105
 106 \membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
 107
 108 \constfunc{wxBitmap}{ConvertToBitmap}{\void}
 109
 110 Converts the image to a platform-specific bitmap object. This has to be done
 111 to actually display an image as you cannot draw an image directly on a window.
 112 The resulting bitmap will use the colour depth of the current system which entails
 113 that a (crude) colour reduction has to take place. When in 8-bit mode, this
 114 routine will use a color cube created on program start-up to look up colors.
 115 Still, the image quality won't be perfect for photo images.
 116
 117 \membersection{wxImage::Create}\label{wximagecreate}
 118
 119 \func{bool}{Create}{\param{int}{ width}, \param{int}{ height}}
 120
 121 Creates a fresh image.
 122
 123 \wxheading{Parameters}
 124
 125 \docparam{width}{The width of the image in pixels.}
 126
 127 \docparam{height}{The height of the image in pixels.}
 128
 129 \wxheading{Return value}
 130
 131 TRUE if the call succeeded, FALSE otherwise.
 132
 133 \membersection{wxImage::Destroy}\label{wximagedestroy}
 134
 135 \func{bool}{Destroy}{\void}
 136
 137 Destroys the image data.
 138
 139 \membersection{wxImage::FindHandler}
 140
 141 \func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}}
 142
 143 Finds the handler with the given name.
 144
 145 \func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{long}{ imageType}}
 146
 147 Finds the handler associated with the given extension and type.
 148
 149 \func{static wxImageHandler*}{FindHandler}{\param{long }{imageType}}
 150
 151 Finds the handler associated with the given image type.
 152
 153 \docparam{name}{The handler name.}
 154
 155 \docparam{extension}{The file extension, such as ``bmp".}
 156
 157 \docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}
 158
 159 \wxheading{Return value}
 160
 161 A pointer to the handler if found, NULL otherwise.
 162
 163 \wxheading{See also}
 164
 165 \helpref{wxImageHandler}{wximagehandler}
 166
 167 \membersection{wxImage::GetBlue}\label{wximagegetblue}
 168
 169 \constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
 170
 171 Returns the blue intensity at the given coordinate.
 172
 173 \membersection{wxImage::GetData}\label{wximagegetdata}
 174
 175 \constfunc{unsigned char*}{GetData}{\void}
 176
 177 Returns the image data as an array. This is most often used when doing
 178 direct image manipulation. The return value points to an array of
 179 chararcters in RGBGBRGB... format.
 180
 181 \membersection{wxImage::GetGreen}\label{wximagegetgreen}
 182
 183 \constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}
 184
 185 Returns the green intensity at the given coordinate.
 186
 187 \membersection{wxImage::GetRed}\label{wximagegetred}
 188
 189 \constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
 190
 191 Returns the red intensity at the given coordinate.
 192
 193 \membersection{wxImage::GetHandlers}
 194
 195 \func{static wxList\&}{GetHandlers}{\void}
 196
 197 Returns the static list of image format handlers.
 198
 199 \wxheading{See also}
 200
 201 \helpref{wxImageHandler}{wximagehandler}
 202
 203 \membersection{wxImage::GetHeight}\label{wximagegetheight}
 204
 205 \constfunc{int}{GetHeight}{\void}
 206
 207 Gets the height of the image in pixels.
 208
 209 \membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}
 210
 211 \constfunc{unsigned char}{GetMaskBlue}{\void}
 212
 213 Gets the blue value of the mask colour.
 214
 215 \membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}
 216
 217 \constfunc{unsigned char}{GetMaskGreen}{\void}
 218
 219 Gets the green value of the mask colour.
 220
 221 \membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}
 222
 223 \constfunc{unsigned char}{GetMaskRed}{\void}
 224
 225 Gets the red value of the mask colour.
 226
 227 \membersection{wxImage::GetWidth}\label{wximagegetwidth}
 228
 229 \constfunc{int}{GetWidth}{\void}
 230
 231 Gets the width of the image in pixels.
 232
 233 \wxheading{See also}
 234
 235 \helpref{wxImage::GetHeight}{wximagegetheight}
 236
 237 \membersection{wxImage::HasMask}\label{wximagehasmask}
 238
 239 \constfunc{bool}{HasMask}{\void}
 240
 241 Returns TRUE if there is a mask active, FALSE otherwise.
 242
 243 \membersection{wxImage::InitStandardHandlers}
 244
 245 \func{static void}{InitStandardHandlers}{\void}
 246
 247 Adds the standard image format handlers, which, depending on wxWindows
 248 configuration, can be handlers for Windows BMP (loading), PNG
 249 (loading and saving) and JPEG (loading and saving) file formats.
 250
 251 This function is called by wxWindows on startup.
 252
 253 \wxheading{See also}
 254
 255 \helpref{wxImageHandler}{wximagehandler}
 256
 257 \membersection{wxImage::InsertHandler}
 258
 259 \func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}
 260
 261 Adds a handler at the start of the static list of format handlers.
 262
 263 \docparam{handler}{A new image format handler object. There is usually only one instance
 264 of a given handler class in an application session.}
 265
 266 \wxheading{See also}
 267
 268 \helpref{wxImageHandler}{wximagehandler}
 269
 270 \membersection{wxImage::LoadFile}\label{wximageloadfile}
 271
 272 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}}
 273
 274 Loads an image from a file.
 275
 276 \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}}
 277
 278 Loads an image from an input stream.
 279
 280 \wxheading{Parameters}
 281
 282 \docparam{name}{A filename.
 283 The meaning of {\it name} is determined by the {\it type} parameter.}
 284
 285 \docparam{stream}{An input stream.
 286 The meaning of {\it stream} data is determined by the {\it type} parameter.}
 287
 288 \docparam{type}{One of the following values:
 289
 290 \twocolwidtha{5cm}%
 291 \begin{twocollist}
 292 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
 293 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
 294 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
 295 \end{twocollist}
 296
 297 The validity of these flags depends on the platform and wxWindows configuration.}
 298
 299 \wxheading{Return value}
 300
 301 TRUE if the operation succeeded, FALSE otherwise.
 302
 303 \wxheading{See also}
 304
 305 \helpref{wxImage::SaveFile}{wximagesavefile}
 306
 307 \membersection{wxImage::Ok}\label{wximageok}
 308
 309 \constfunc{bool}{Ok}{\void}
 310
 311 Returns TRUE if image data is present.
 312
 313 \membersection{wxImage::RemoveHandler}
 314
 315 \func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
 316
 317 Finds the handler with the given name, and removes it. The handler
 318 is not deleted.
 319
 320 \docparam{name}{The handler name.}
 321
 322 \wxheading{Return value}
 323
 324 TRUE if the handler was found and removed, FALSE otherwise.
 325
 326 \wxheading{See also}
 327
 328 \helpref{wxImageHandler}{wximagehandler}
 329
 330 \membersection{wxImage::SaveFile}\label{wximagesavefile}
 331
 332 \func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
 333
 334 Saves a image in the named file.
 335
 336 \func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
 337
 338 Saves a image in the given stream.
 339
 340 \wxheading{Parameters}
 341
 342 \docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
 343
 344 \docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
 345
 346 \docparam{type}{Currently two types can be used:
 347
 348 \twocolwidtha{5cm}%
 349 \begin{twocollist}
 350 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
 351 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
 352 \end{twocollist}
 353
 354 The validity of these flags depends on the platform and wxWindows configuration
 355 as well as user-added handlers.}
 356
 357 \wxheading{Return value}
 358
 359 TRUE if the operation succeeded, FALSE otherwise.
 360
 361 \wxheading{Remarks}
 362
 363 Depending on how wxWindows has been configured, not all formats may be available.
 364
 365 \wxheading{See also}
 366
 367 \helpref{wxImage::LoadFile}{wximageloadfile}
 368
 369 \membersection{wxImage::Scale}\label{wximagescale}
 370
 371 \func{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
 372
 373 Returns a scaled version of the image. This is also useful for
 374 scaling bitmaps in general as the only other way to scale bitmaps
 375 is to blit a wxMemoryDC into another wxMemoryDC. Windows can do such
 376 scaling itself but in the GTK port, scaling bitmaps is done using
 377 this routine internally.
 378
 379 \membersection{wxImage::SetData}\label{wximagesetdata}
 380
 381 \func{void}{SetData}{\param{unsigned char*}{data}}
 382
 383 Sets the image data without performing checks. The data given must have
 384 the size (width*height*3) or results will be unexpected. Don't use this
 385 method if you aren't sure you know what you are doing.
 386
 387 \membersection{wxImage::SetMask}\label{wximagesetmask}
 388
 389 \func{void}{SetMask}{\param{bool}{ hasMask = TRUE}}
 390
 391 Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
 392
 393 \membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
 394
 395 \func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
 396
 397 Sets the mask colour for this image (and tells the image to use the mask).
 398
 399 \membersection{wxImage::SetRGB}\label{wximagesetrgb}
 400
 401 \func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
 402
 403 Sets the pixel at the given coordinate. This routine performs bounds-checks
 404 for the coordinate so it can be considered a safe way to manipulate the
 405 data, but in some cases this might be too slow so that the data will have to
 406 be set directly. In that case you have to get that data by calling GetData().
 407
 408 \membersection{wxImage::operator $=$}
 409
 410 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
 411
 412 Assignment operator. This operator does not copy any data, but instead
 413 passes a pointer to the data in {\it image} and increments a reference
 414 counter. It is a fast operation.
 415
 416 \wxheading{Parameters}
 417
 418 \docparam{image}{Image to assign.}
 419
 420 \wxheading{Return value}
 421
 422 Returns 'this' object.
 423
 424 \membersection{wxImage::operator $==$}
 425
 426 \func{bool}{operator $==$}{\param{const wxImage\& }{image}}
 427
 428 Equality operator. This operator tests whether the internal data pointers are
 429 equal (a fast test).
 430
 431 \wxheading{Parameters}
 432
 433 \docparam{image}{Image to compare with 'this'}
 434
 435 \wxheading{Return value}
 436
 437 Returns TRUE if the images were effectively equal, FALSE otherwise.
 438
 439 \membersection{wxImage::operator $!=$}
 440
 441 \func{bool}{operator $!=$}{\param{const wxImage\& }{image}}
 442
 443 Inequality operator. This operator tests whether the internal data pointers are
 444 unequal (a fast test).
 445
 446 \wxheading{Parameters}
 447
 448 \docparam{image}{Image to compare with 'this'}
 449
 450 \wxheading{Return value}
 451
 452 Returns TRUE if the images were unequal, FALSE otherwise.
 453
 454 \section{\class{wxImageHandler}}\label{wximagehandler}
 455
 456 This is the base class for implementing image file loading/saving, and image creation from data.
 457 It is used within wxImage and is not normally seen by the application.
 458
 459 If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
 460 and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
 461 application initialisation.
 462
 463 \wxheading{Note (Legal Issue)}
 464
 465 This software is based in part on the work of
 466  the Independent JPEG Group.
 467
 468 (Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
 469 created by IJG.)
 470
 471 \wxheading{Derived from}
 472
 473 \helpref{wxObject}{wxobject}
 474
 475 \wxheading{See also}
 476
 477 \helpref{wxImage}{wximage}
 478
 479 \latexignore{\rtfignore{\wxheading{Members}}}
 480
 481 \membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerconstr}
 482
 483 \func{}{wxImageHandler}{\void}
 484
 485 Default constructor. In your own default constructor, initialise the members
 486 m\_name, m\_extension and m\_type.
 487
 488 \membersection{wxImageHandler::\destruct{wxImageHandler}}
 489
 490 \func{}{\destruct{wxImageHandler}}{\void}
 491
 492 Destroys the wxImageHandler object.
 493
 494 \membersection{wxImageHandler::GetName}
 495
 496 \constfunc{wxString}{GetName}{\void}
 497
 498 Gets the name of this handler.
 499
 500 \membersection{wxImageHandler::GetExtension}
 501
 502 \constfunc{wxString}{GetExtension}{\void}
 503
 504 Gets the file extension associated with this handler.
 505
 506 \membersection{wxImageHandler::GetType}
 507
 508 \constfunc{long}{GetType}{\void}
 509
 510 Gets the image type associated with this handler.
 511
 512 \membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
 513
 514 \func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}}
 515
 516 Loads a image from a stream, putting the resulting data into {\it image}.
 517
 518 \wxheading{Parameters}
 519
 520 \docparam{image}{The image object which is to be affected by this operation.}
 521
 522 \docparam{stream}{Opened input stream.
 523 The meaning of {\it stream} is determined by the {\it type} parameter.}
 524
 525 \wxheading{Return value}
 526
 527 TRUE if the operation succeeded, FALSE otherwise.
 528
 529 \wxheading{See also}
 530
 531 \helpref{wxImage::LoadFile}{wximageloadfile}\\
 532 \helpref{wxImage::SaveFile}{wximagesavefile}\\
 533 \helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
 534
 535 \membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
 536
 537 \func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
 538
 539 Saves a image in the output stream.
 540
 541 \wxheading{Parameters}
 542
 543 \docparam{image}{The image object which is to be affected by this operation.}
 544
 545 \docparam{stream}{A stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
 546
 547 \wxheading{Return value}
 548
 549 TRUE if the operation succeeded, FALSE otherwise.
 550
 551 \wxheading{See also}
 552
 553 \helpref{wxImage::LoadFile}{wximageloadfile}\\
 554 \helpref{wxImage::SaveFile}{wximagesavefile}\\
 555 \helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
 556
 557 \membersection{wxImageHandler::SetName}
 558
 559 \func{void}{SetName}{\param{const wxString\& }{name}}
 560
 561 Sets the handler name.
 562
 563 \wxheading{Parameters}
 564
 565 \docparam{name}{Handler name.}
 566
 567 \membersection{wxImageHandler::SetExtension}
 568
 569 \func{void}{SetExtension}{\param{const wxString\& }{extension}}
 570
 571 Sets the handler extension.
 572
 573 \wxheading{Parameters}
 574
 575 \docparam{extension}{Handler extension.}
 576
 577 \membersection{wxImageHandler::SetType}
 578
 579 \func{void}{SetType}{\param{long }{type}}
 580
 581 Sets the handler type.
 582
 583 \wxheading{Parameters}
 584
 585 \docparam{name}{Handler type.}
 586