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