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