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