1wxImage(3) Erlang Module Definition wxImage(3)
2
6 wxImage - Functions for wxImage class
7
9 This class encapsulates a platform-independent image.
10 An image can be created from data, or using wxBitmap:convertToImage/1.
12 An image can be loaded from a file in a variety of formats, and is ex‐
13 tensible to new formats via image format handlers. Functions are avail‐
14 able to set and get image bits, so it can be used for basic image ma‐
15 nipulation.
16 A wxImage cannot (currently) be drawn directly to a wxDC. Instead, a
18 platform-specific wxBitmap object must be created from it using the
19 wxBitmap::wxBitmap(wxImage,int depth) constructor. This bitmap can then
20 be drawn in a device context, using wxDC:drawBitmap/4.
21 More on the difference between wxImage and wxBitmap: wxImage is just a
23 buffer of RGB bytes with an optional buffer for the alpha bytes. It is
24 all generic, platform independent and image file format independent
25 code. It includes generic code for scaling, resizing, clipping, and
26 other manipulations of the image data. OTOH, wxBitmap is intended to be
27 a wrapper of whatever is the native image format that is quickest/easi‐
28 est to draw to a DC or to be the target of the drawing operations per‐
29 formed on a wxMemoryDC. By splitting the responsibilities between wxIm‐
30 age/wxBitmap like this then it's easier to use generic code shared by
31 all platforms and image types for generic operations and platform spe‐
32 cific code where performance or compatibility is needed.
33 One colour value of the image may be used as a mask colour which will
35 lead to the automatic creation of a wxMask object associated to the
36 bitmap object.
37 Alpha channel support
39 Starting from wxWidgets 2.5.0 wxImage supports alpha channel data, that
41 is in addition to a byte for the red, green and blue colour components
42 for each pixel it also stores a byte representing the pixel opacity.
43 An alpha value of 0 corresponds to a transparent pixel (null opacity)
45 while a value of 255 means that the pixel is 100% opaque. The constants
46 ?wxIMAGE_ALPHA_TRANSPARENT and ?wxIMAGE_ALPHA_OPAQUE can be used to in‐
47 dicate those values in a more readable form.
48 While all images have RGB data, not all images have an alpha channel.
50 Before using getAlpha/3 you should check if this image contains an al‐
51 pha channel with hasAlpha/1. Currently the BMP, PNG, TGA, and TIFF for‐
52 mat handlers have full alpha channel support for loading so if you want
53 to use alpha you have to use one of these formats. If you initialize
54 the image alpha channel yourself using setAlpha/4, you should save it
55 in either PNG, TGA, or TIFF format to avoid losing it as these are the
56 only handlers that currently support saving with alpha.
57 Available image handlers
59 The following image handlers are available. wxBMPHandler is always in‐
61 stalled by default. To use other image formats, install the appropriate
62 handler with wxImage::AddHandler (not implemented in wx) or call ?wx‐
63 InitAllImageHandlers().
64 When saving in PCX format, wxPCXHandler (not implemented in wx) will
66 count the number of different colours in the image; if there are 256 or
67 less colours, it will save as 8 bit, else it will save as 24 bit.
68 Loading PNMs only works for ASCII or raw RGB images. When saving in PNM
70 format, wxPNMHandler (not implemented in wx) will always save as raw
71 RGB.
72 Saving GIFs requires images of maximum 8 bpp (see wxQuantize (not im‐
74 plemented in wx)), and the alpha channel converted to a mask (see con‐
75 vertAlphaToMask/5). Saving an animated GIF requires images of the same
76 size (see wxGIFHandler::SaveAnimation (not implemented in wx))
77 Predefined objects (include wx.hrl): ?wxNullImage
79 See: wxBitmap, ?wxInitAllImageHandlers(), wxPixelData (not implemented
81 in wx)
82 wxWidgets docs: wxImage
84
86 wxImage() = wx:wx_object()
87
89 new() -> wxImage()
90 Creates an empty wxImage object without an alpha channel.
92 new(Name) -> wxImage()
94 new(Sz) -> wxImage()
96 Types:
98 Sz = {W :: integer(), H :: integer()}
100 new(Width, Height) -> wxImage()
102 new(Sz, Data) -> wxImage()
104 new(Name, Height :: [Option]) -> wxImage()
106 new(Sz, Height :: [Option]) -> wxImage()
108 Types:
110 Sz = {W :: integer(), H :: integer()}
112 Option = {clear, boolean()}
113 This is an overloaded member function, provided for convenience.
115 It differs from the above function only in what argument(s) it
116 accepts.
117 new(Width, Height, Data) -> wxImage()
119 new(Sz, Data, Alpha) -> wxImage()
121 new(Width, Height, Data :: [Option]) -> wxImage()
123 new(Name, Mimetype, Data :: [Option]) -> wxImage()
125 new(Sz, Data, Data :: [Option]) -> wxImage()
127 Types:
129 Sz = {W :: integer(), H :: integer()}
131 Data = binary()
132 Option = {static_data, boolean()}
133 This is an overloaded member function, provided for convenience.
135 It differs from the above function only in what argument(s) it
136 accepts.
137 new(Width, Height, Data, Alpha) -> wxImage()
139 new(Width, Height, Data, Alpha :: [Option]) -> wxImage()
141 new(Sz, Data, Alpha, Alpha :: [Option]) -> wxImage()
143 Types:
145 Sz = {W :: integer(), H :: integer()}
147 Data = Alpha = binary()
148 Option = {static_data, boolean()}
149 This is an overloaded member function, provided for convenience.
151 It differs from the above function only in what argument(s) it
152 accepts.
153 new(Width, Height, Data, Alpha, Options :: [Option]) -> wxImage()
155 Types:
157 Width = Height = integer()
159 Data = Alpha = binary()
160 Option = {static_data, boolean()}
161 Creates an image from data in memory.
163 If static_data is false then the wxImage will take ownership of
165 the data and free it afterwards. For this, it has to be allo‐
166 cated with malloc.
167 destroy(This :: wxImage()) -> ok
169 Destructor.
171 See reference-counted object destruction for more info.
173 blur(This, BlurRadius) -> wxImage()
175 Types:
177 This = wxImage()
179 BlurRadius = integer()
180 Blurs the image in both horizontal and vertical directions by
182 the specified pixel blurRadius.
183 This should not be used when using a single mask colour for
185 transparency.
186 See: blurHorizontal/2, blurVertical/2
188 blurHorizontal(This, BlurRadius) -> wxImage()
190 Types:
192 This = wxImage()
194 BlurRadius = integer()
195 Blurs the image in the horizontal direction only.
197 This should not be used when using a single mask colour for
199 transparency.
200 See: blur/2, blurVertical/2
202 blurVertical(This, BlurRadius) -> wxImage()
204 Types:
206 This = wxImage()
208 BlurRadius = integer()
209 Blurs the image in the vertical direction only.
211 This should not be used when using a single mask colour for
213 transparency.
214 See: blur/2, blurHorizontal/2
216 convertAlphaToMask(This) -> boolean()
218 Types:
220 This = wxImage()
222 convertAlphaToMask(This, Options :: [Option]) -> boolean()
224 Types:
226 This = wxImage()
228 Option = {threshold, integer()}
229 If the image has alpha channel, this method converts it to mask.
231 If the image has an alpha channel, all pixels with alpha value
233 less than threshold are replaced with the mask colour and the
234 alpha channel is removed. Otherwise nothing is done.
235 The mask colour is chosen automatically using findFirstUnused‐
237 Colour/2, see the overload below if this is not appropriate.
238 Return: Returns true on success, false on error.
240 convertAlphaToMask(This, Mr, Mg, Mb) -> boolean()
242 Types:
244 This = wxImage()
246 Mr = Mg = Mb = integer()
247 convertAlphaToMask(This, Mr, Mg, Mb, Options :: [Option]) ->
249 boolean()
250 Types:
252 This = wxImage()
254 Mr = Mg = Mb = integer()
255 Option = {threshold, integer()}
256 If the image has alpha channel, this method converts it to mask
258 using the specified colour as the mask colour.
259 If the image has an alpha channel, all pixels with alpha value
261 less than threshold are replaced with the mask colour and the
262 alpha channel is removed. Otherwise nothing is done.
263 Since: 2.9.0
265 Return: Returns true on success, false on error.
267 convertToGreyscale(This) -> wxImage()
269 Types:
271 This = wxImage()
273 Returns a greyscale version of the image.
275 Since: 2.9.0
277 convertToGreyscale(This, Weight_r, Weight_g, Weight_b) ->
279 wxImage()
280 Types:
282 This = wxImage()
284 Weight_r = Weight_g = Weight_b = number()
285 Returns a greyscale version of the image.
287 The returned image uses the luminance component of the original
289 to calculate the greyscale. Defaults to using the standard ITU-T
290 BT.601 when converting to YUV, where every pixel equals (R *
291 weight_r) + (G * weight_g) + (B * weight_b).
292 convertToMono(This, R, G, B) -> wxImage()
294 Types:
296 This = wxImage()
298 R = G = B = integer()
299 Returns monochromatic version of the image.
301 The returned image has white colour where the original has
303 (r,g,b) colour and black colour everywhere else.
304 copy(This) -> wxImage()
306 Types:
308 This = wxImage()
310 Returns an identical copy of this image.
312 create(This, Sz) -> boolean()
314 Types:
316 This = wxImage()
318 Sz = {W :: integer(), H :: integer()}
319 create(This, Width, Height) -> boolean()
321 create(This, Sz, Data) -> boolean()
323 create(This, Sz, Height :: [Option]) -> boolean()
325 Types:
327 This = wxImage()
329 Sz = {W :: integer(), H :: integer()}
330 Option = {clear, boolean()}
331 This is an overloaded member function, provided for convenience.
333 It differs from the above function only in what argument(s) it
334 accepts.
335 create(This, Width, Height, Data) -> boolean()
337 create(This, Sz, Data, Alpha) -> boolean()
339 create(This, Width, Height, Data :: [Option]) -> boolean()
341 create(This, Sz, Data, Data :: [Option]) -> boolean()
343 Types:
345 This = wxImage()
347 Sz = {W :: integer(), H :: integer()}
348 Data = binary()
349 Option = {static_data, boolean()}
350 This is an overloaded member function, provided for convenience.
352 It differs from the above function only in what argument(s) it
353 accepts.
354 create(This, Width, Height, Data, Alpha) -> boolean()
356 create(This, Width, Height, Data, Alpha :: [Option]) -> boolean()
358 create(This, Sz, Data, Alpha, Alpha :: [Option]) -> boolean()
360 Types:
362 This = wxImage()
364 Sz = {W :: integer(), H :: integer()}
365 Data = Alpha = binary()
366 Option = {static_data, boolean()}
367 This is an overloaded member function, provided for convenience.
369 It differs from the above function only in what argument(s) it
370 accepts.
371 create(This, Width, Height, Data, Alpha, Options :: [Option]) ->
373 boolean()
374 Types:
376 This = wxImage()
378 Width = Height = integer()
379 Data = Alpha = binary()
380 Option = {static_data, boolean()}
381 Creates a fresh image.
383 See new/5 for more info.
385 Return: true if the call succeeded, false otherwise.
387 'Destroy'(This) -> ok
389 Types:
391 This = wxImage()
393 Destroys the image data.
395 findFirstUnusedColour(This) -> Result
397 Types:
399 Result =
401 {Res :: boolean(),
402 R :: integer(),
403 G :: integer(),
404 B :: integer()}
405 This = wxImage()
406 findFirstUnusedColour(This, Options :: [Option]) -> Result
408 Types:
410 Result =
412 {Res :: boolean(),
413 R :: integer(),
414 G :: integer(),
415 B :: integer()}
416 This = wxImage()
417 Option =
418 {startR, integer()} |
419 {startG, integer()} |
420 {startB, integer()}
421 Finds the first colour that is never used in the image.
423 The search begins at given initial colour and continues by in‐
425 creasing R, G and B components (in this order) by 1 until an un‐
426 used colour is found or the colour space exhausted.
427 The parameters r, g, b are pointers to variables to save the
429 colour.
430 The parameters startR, startG, startB define the initial values
432 of the colour. The returned colour will have RGB values equal to
433 or greater than these.
434 Return: Returns false if there is no unused colour left, true on
436 success.
437 Note: This method involves computing the histogram, which is a
439 computationally intensive operation.
440 getImageExtWildcard() -> unicode:charlist()
442 Iterates all registered wxImageHandler (not implemented in wx)
444 objects, and returns a string containing file extension masks
445 suitable for passing to file open/save dialog boxes.
446 Return: The format of the returned string is
448 "(*.ext1;*.ext2)|*.ext1;*.ext2". It is usually a good idea to
449 prepend a description before passing the result to the dialog.
450 Example:
451 See: wxImageHandler (not implemented in wx)
453 getAlpha(This) -> binary()
455 Types:
457 This = wxImage()
459 Returns pointer to the array storing the alpha values for this
461 image.
462 This pointer is NULL for the images without the alpha channel.
464 If the image does have it, this pointer may be used to directly
465 manipulate the alpha values which are stored as the RGB ones.
466 getAlpha(This, X, Y) -> integer()
468 Types:
470 This = wxImage()
472 X = Y = integer()
473 Return alpha value at given pixel location.
475 getBlue(This, X, Y) -> integer()
477 Types:
479 This = wxImage()
481 X = Y = integer()
482 Returns the blue intensity at the given coordinate.
484 getData(This) -> binary()
486 Types:
488 This = wxImage()
490 Returns the image data as an array.
492 This is most often used when doing direct image manipulation.
494 The return value points to an array of characters in RGBRG‐
495 BRGB... format in the top-to-bottom, left-to-right order, that
496 is the first RGB triplet corresponds to the first pixel of the
497 first row, the second one - to the second pixel of the first row
498 and so on until the end of the first row, with second row fol‐
499 lowing after it and so on.
500 You should not delete the returned pointer nor pass it to set‐
502 Data/5.
503 getGreen(This, X, Y) -> integer()
505 Types:
507 This = wxImage()
509 X = Y = integer()
510 Returns the green intensity at the given coordinate.
512 getImageCount(Filename) -> integer()
514 Types:
516 Filename = unicode:chardata()
518 getImageCount(Filename, Options :: [Option]) -> integer()
520 Types:
522 Filename = unicode:chardata()
524 Option = {type, wx:wx_enum()}
525 If the image file contains more than one image and the image
527 handler is capable of retrieving these individually, this func‐
528 tion will return the number of available images.
529 For the overload taking the parameter filename, that's the name
531 of the file to query. For the overload taking the parameter
532 stream, that's the opened input stream with image data.
533 See wxImageHandler::GetImageCount() (not implemented in wx) for
535 more info.
536 The parameter type may be one of the following values:
538 Return: Number of available images. For most image handlers,
540 this is 1 (exceptions are TIFF and ICO formats as well as ani‐
541 mated GIFs for which this function returns the number of frames
542 in the animation).
543 getHeight(This) -> integer()
545 Types:
547 This = wxImage()
549 Gets the height of the image in pixels.
551 See: getWidth/1, GetSize() (not implemented in wx)
553 getMaskBlue(This) -> integer()
555 Types:
557 This = wxImage()
559 Gets the blue value of the mask colour.
561 getMaskGreen(This) -> integer()
563 Types:
565 This = wxImage()
567 Gets the green value of the mask colour.
569 getMaskRed(This) -> integer()
571 Types:
573 This = wxImage()
575 Gets the red value of the mask colour.
577 getOrFindMaskColour(This) -> Result
579 Types:
581 Result =
583 {Res :: boolean(),
584 R :: integer(),
585 G :: integer(),
586 B :: integer()}
587 This = wxImage()
588 Get the current mask colour or find a suitable unused colour
590 that could be used as a mask colour.
591 Returns true if the image currently has a mask.
593 getPalette(This) -> wxPalette:wxPalette()
595 Types:
597 This = wxImage()
599 Returns the palette associated with the image.
601 Currently the palette is only used when converting to wxBitmap
603 under Windows.
604 Some of the wxImage handlers have been modified to set the pal‐
606 ette if one exists in the image file (usually 256 or less colour
607 images in GIF or PNG format).
608 getRed(This, X, Y) -> integer()
610 Types:
612 This = wxImage()
614 X = Y = integer()
615 Returns the red intensity at the given coordinate.
617 getSubImage(This, Rect) -> wxImage()
619 Types:
621 This = wxImage()
623 Rect =
624 {X :: integer(),
625 Y :: integer(),
626 W :: integer(),
627 H :: integer()}
628 Returns a sub image of the current one as long as the rect be‐
630 longs entirely to the image.
631 getWidth(This) -> integer()
633 Types:
635 This = wxImage()
637 Gets the width of the image in pixels.
639 See: getHeight/1, GetSize() (not implemented in wx)
641 hasAlpha(This) -> boolean()
643 Types:
645 This = wxImage()
647 Returns true if this image has alpha channel, false otherwise.
649 See: getAlpha/3, setAlpha/4
651 hasMask(This) -> boolean()
653 Types:
655 This = wxImage()
657 Returns true if there is a mask active, false otherwise.
659 getOption(This, Name) -> unicode:charlist()
661 Types:
663 This = wxImage()
665 Name = unicode:chardata()
666 Gets a user-defined string-valued option.
668 Generic options:
670 Options specific to wxGIFHandler (not implemented in wx):
672 Return: The value of the option or an empty string if not found.
674 Use hasOption/2 if an empty string can be a valid option value.
675 See: setOption/3, getOptionInt/2, hasOption/2
677 getOptionInt(This, Name) -> integer()
679 Types:
681 This = wxImage()
683 Name = unicode:chardata()
684 Gets a user-defined integer-valued option.
686 The function is case-insensitive to name. If the given option is
688 not present, the function returns 0. Use hasOption/2 if 0 is a
689 possibly valid value for the option.
690 Generic options:
692 Since: 2.9.3
694 Options specific to wxPNGHandler (not implemented in wx):
696 Options specific to wxTIFFHandler (not implemented in wx):
698 Options specific to wxGIFHandler (not implemented in wx):
700 Note: Be careful when combining the options wxIMAGE_OP‐
702 TION_TIFF_SAMPLESPERPIXEL, wxIMAGE_OPTION_TIFF_BITSPERSAMPLE,
703 and wxIMAGE_OPTION_TIFF_PHOTOMETRIC. While some measures are
704 taken to prevent illegal combinations and/or values, it is still
705 easy to abuse them and come up with invalid results in the form
706 of either corrupted images or crashes.
707 Return: The value of the option or 0 if not found. Use hasOp‐
709 tion/2 if 0 can be a valid option value.
710 See: setOption/3, getOption/2
712 hasOption(This, Name) -> boolean()
714 Types:
716 This = wxImage()
718 Name = unicode:chardata()
719 Returns true if the given option is present.
721 The function is case-insensitive to name.
723 The lists of the currently supported options are in getOption/2
725 and getOptionInt/2 function docs.
726 See: setOption/3, getOption/2, getOptionInt/2
728 initAlpha(This) -> ok
730 Types:
732 This = wxImage()
734 Initializes the image alpha channel data.
736 It is an error to call it if the image already has alpha data.
738 If it doesn't, alpha data will be by default initialized to all
739 pixels being fully opaque. But if the image has a mask colour,
740 all mask pixels will be completely transparent.
741 initStandardHandlers() -> ok
743 Internal use only.
745 Adds standard image format handlers. It only install wxBMPHan‐
747 dler for the time being, which is used by wxBitmap.
748 This function is called by wxWidgets on startup, and shouldn't
750 be called by the user.
751 See: wxImageHandler (not implemented in wx), ?wxInitAllImageHan‐
753 dlers(), wxQuantize (not implemented in wx)
754 isTransparent(This, X, Y) -> boolean()
756 Types:
758 This = wxImage()
760 X = Y = integer()
761 isTransparent(This, X, Y, Options :: [Option]) -> boolean()
763 Types:
765 This = wxImage()
767 X = Y = integer()
768 Option = {threshold, integer()}
769 Returns true if the given pixel is transparent, i.e. either has
771 the mask colour if this image has a mask or if this image has
772 alpha channel and alpha value of this pixel is strictly less
773 than threshold.
774 loadFile(This, Name) -> boolean()
776 Types:
778 This = wxImage()
780 Name = unicode:chardata()
781 loadFile(This, Name, Options :: [Option]) -> boolean()
783 Types:
785 This = wxImage()
787 Name = unicode:chardata()
788 Option = {type, wx:wx_enum()} | {index, integer()}
789 Loads an image from a file.
791 If no handler type is provided, the library will try to autode‐
793 tect the format.
794 loadFile(This, Name, Mimetype, Options :: [Option]) -> boolean()
796 Types:
798 This = wxImage()
800 Name = Mimetype = unicode:chardata()
801 Option = {index, integer()}
802 Loads an image from a file.
804 If no handler type is provided, the library will try to autode‐
806 tect the format.
807 ok(This) -> boolean()
809 Types:
811 This = wxImage()
813 See: isOk/1.
815 isOk(This) -> boolean()
817 Types:
819 This = wxImage()
821 Returns true if image data is present.
823 removeHandler(Name) -> boolean()
825 Types:
827 Name = unicode:chardata()
829 Finds the handler with the given name, and removes it.
831 The handler is also deleted.
833 Return: true if the handler was found and removed, false other‐
835 wise.
836 See: wxImageHandler (not implemented in wx)
838 mirror(This) -> wxImage()
840 Types:
842 This = wxImage()
844 mirror(This, Options :: [Option]) -> wxImage()
846 Types:
848 This = wxImage()
850 Option = {horizontally, boolean()}
851 Returns a mirrored copy of the image.
853 The parameter horizontally indicates the orientation.
855 replace(This, R1, G1, B1, R2, G2, B2) -> ok
857 Types:
859 This = wxImage()
861 R1 = G1 = B1 = R2 = G2 = B2 = integer()
862 Replaces the colour specified by r1,g1,b1 by the colour
864 r2,g2,b2.
865 rescale(This, Width, Height) -> wxImage()
867 Types:
869 This = wxImage()
871 Width = Height = integer()
872 rescale(This, Width, Height, Options :: [Option]) -> wxImage()
874 Types:
876 This = wxImage()
878 Width = Height = integer()
879 Option = {quality, wx:wx_enum()}
880 Changes the size of the image in-place by scaling it: after a
882 call to this function,the image will have the given width and
883 height.
884 For a description of the quality parameter, see the scale/4
886 function. Returns the (modified) image itself.
887 See: scale/4
889 resize(This, Size, Pos) -> wxImage()
891 Types:
893 This = wxImage()
895 Size = {W :: integer(), H :: integer()}
896 Pos = {X :: integer(), Y :: integer()}
897 resize(This, Size, Pos, Options :: [Option]) -> wxImage()
899 Types:
901 This = wxImage()
903 Size = {W :: integer(), H :: integer()}
904 Pos = {X :: integer(), Y :: integer()}
905 Option = {r, integer()} | {g, integer()} | {b, integer()}
906 Changes the size of the image in-place without scaling it by
908 adding either a border with the given colour or cropping as nec‐
909 essary.
910 The image is pasted into a new image with the given size and
912 background colour at the position pos relative to the upper left
913 of the new image.
914 If red = green = blue = -1 then use either the current mask
916 colour if set or find, use, and set a suitable mask colour for
917 any newly exposed areas.
918 Return: The (modified) image itself.
920 See: size/4
922 rotate(This, Angle, RotationCentre) -> wxImage()
924 Types:
926 This = wxImage()
928 Angle = number()
929 RotationCentre = {X :: integer(), Y :: integer()}
930 rotate(This, Angle, RotationCentre, Options :: [Option]) ->
932 wxImage()
933 Types:
935 This = wxImage()
937 Angle = number()
938 RotationCentre = {X :: integer(), Y :: integer()}
939 Option =
940 {interpolating, boolean()} |
941 {offset_after_rotation, {X :: integer(), Y :: integer()}}
942 Rotates the image about the given point, by angle radians.
944 Passing true to interpolating results in better image quality,
946 but is slower.
947 If the image has a mask, then the mask colour is used for the
949 uncovered pixels in the rotated image background. Else, black
950 (rgb 0, 0, 0) will be used.
951 Returns the rotated image, leaving this image intact.
953 rotateHue(This, Angle) -> ok
955 Types:
957 This = wxImage()
959 Angle = number()
960 Rotates the hue of each pixel in the image by angle, which is a
962 double in the range of -1.0 to +1.0, where -1.0 corresponds to
963 -360 degrees and +1.0 corresponds to +360 degrees.
964 rotate90(This) -> wxImage()
966 Types:
968 This = wxImage()
970 rotate90(This, Options :: [Option]) -> wxImage()
972 Types:
974 This = wxImage()
976 Option = {clockwise, boolean()}
977 Returns a copy of the image rotated 90 degrees in the direction
979 indicated by clockwise.
980 saveFile(This, Name) -> boolean()
982 Types:
984 This = wxImage()
986 Name = unicode:chardata()
987 Saves an image in the named file.
989 File type is determined from the extension of the file name.
991 Note that this function may fail if the extension is not recog‐
992 nized! You can use one of the forms above to save images to
993 files with non-standard extensions.
994 saveFile(This, Name, Type) -> boolean()
996 saveFile(This, Name, Mimetype) -> boolean()
998 Types:
1000 This = wxImage()
1002 Name = Mimetype = unicode:chardata()
1003 Saves an image in the named file.
1005 scale(This, Width, Height) -> wxImage()
1007 Types:
1009 This = wxImage()
1011 Width = Height = integer()
1012 scale(This, Width, Height, Options :: [Option]) -> wxImage()
1014 Types:
1016 This = wxImage()
1018 Width = Height = integer()
1019 Option = {quality, wx:wx_enum()}
1020 Returns a scaled version of the image.
1022 This is also useful for scaling bitmaps in general as the only
1024 other way to scale bitmaps is to blit a wxMemoryDC into another
1025 wxMemoryDC.
1026 The parameter quality determines what method to use for resam‐
1028 pling the image, see wxImageResizeQuality documentation.
1029 It should be noted that although using wxIMAGE_QUALITY_HIGH pro‐
1031 duces much nicer looking results it is a slower method. Downsam‐
1032 pling will use the box averaging method which seems to operate
1033 very fast. If you are upsampling larger images using this method
1034 you will most likely notice that it is a bit slower and in ex‐
1035 treme cases it will be quite substantially slower as the bicubic
1036 algorithm has to process a lot of data.
1037 It should also be noted that the high quality scaling may not
1039 work as expected when using a single mask colour for transpar‐
1040 ency, as the scaling will blur the image and will therefore re‐
1041 move the mask partially. Using the alpha channel will work.
1042 Example:
1044 See: rescale/4
1046 size(This, Size, Pos) -> wxImage()
1048 Types:
1050 This = wxImage()
1052 Size = {W :: integer(), H :: integer()}
1053 Pos = {X :: integer(), Y :: integer()}
1054 size(This, Size, Pos, Options :: [Option]) -> wxImage()
1056 Types:
1058 This = wxImage()
1060 Size = {W :: integer(), H :: integer()}
1061 Pos = {X :: integer(), Y :: integer()}
1062 Option = {r, integer()} | {g, integer()} | {b, integer()}
1063 Returns a resized version of this image without scaling it by
1065 adding either a border with the given colour or cropping as nec‐
1066 essary.
1067 The image is pasted into a new image with the given size and
1069 background colour at the position pos relative to the upper left
1070 of the new image.
1071 If red = green = blue = -1 then the areas of the larger image
1073 not covered by this image are made transparent by filling them
1074 with the image mask colour (which will be allocated automati‐
1075 cally if it isn't currently set).
1076 Otherwise, the areas will be filled with the colour with the
1078 specified RGB components.
1079 See: resize/4
1081 setAlpha(This, Alpha) -> ok
1083 Types:
1085 This = wxImage()
1087 Alpha = binary()
1088 setAlpha(This, Alpha, Options :: [Option]) -> ok
1090 Types:
1092 This = wxImage()
1094 Alpha = binary()
1095 Option = {static_data, boolean()}
1096 This function is similar to setData/5 and has similar restric‐
1098 tions.
1099 The pointer passed to it may however be NULL in which case the
1101 function will allocate the alpha array internally - this is use‐
1102 ful to add alpha channel data to an image which doesn't have
1103 any.
1104 If the pointer is not NULL, it must have one byte for each image
1106 pixel and be allocated with malloc(). wxImage takes ownership of
1107 the pointer and will free it unless static_data parameter is set
1108 to true - in this case the caller should do it.
1109 setAlpha(This, X, Y, Alpha) -> ok
1111 Types:
1113 This = wxImage()
1115 X = Y = Alpha = integer()
1116 Sets the alpha value for the given pixel.
1118 This function should only be called if the image has alpha chan‐
1120 nel data, use hasAlpha/1 to check for this.
1121 setData(This, Data) -> ok
1123 Types:
1125 This = wxImage()
1127 Data = binary()
1128 setData(This, Data, Options :: [Option]) -> ok
1130 Types:
1132 This = wxImage()
1134 Data = binary()
1135 Option = {static_data, boolean()}
1136 Sets the image data without performing checks.
1138 The data given must have the size (width*height*3) or results
1140 will be unexpected. Don't use this method if you aren't sure you
1141 know what you are doing.
1142 The data must have been allocated with malloc(), NOT with opera‐
1144 tor new.
1145 If static_data is false, after this call the pointer to the data
1147 is owned by the wxImage object, that will be responsible for
1148 deleting it. Do not pass to this function a pointer obtained
1149 through getData/1.
1150 setData(This, Data, New_width, New_height) -> ok
1152 Types:
1154 This = wxImage()
1156 Data = binary()
1157 New_width = New_height = integer()
1158 setData(This, Data, New_width, New_height, Options :: [Option]) ->
1160 ok
1161 Types:
1163 This = wxImage()
1165 Data = binary()
1166 New_width = New_height = integer()
1167 Option = {static_data, boolean()}
1168 This is an overloaded member function, provided for convenience.
1170 It differs from the above function only in what argument(s) it
1171 accepts.
1172 setMask(This) -> ok
1174 Types:
1176 This = wxImage()
1178 setMask(This, Options :: [Option]) -> ok
1180 Types:
1182 This = wxImage()
1184 Option = {mask, boolean()}
1185 Specifies whether there is a mask or not.
1187 The area of the mask is determined by the current mask colour.
1189 setMaskColour(This, Red, Green, Blue) -> ok
1191 Types:
1193 This = wxImage()
1195 Red = Green = Blue = integer()
1196 Sets the mask colour for this image (and tells the image to use
1198 the mask).
1199 setMaskFromImage(This, Mask, Mr, Mg, Mb) -> boolean()
1201 Types:
1203 This = Mask = wxImage()
1205 Mr = Mg = Mb = integer()
1206 Sets image's mask so that the pixels that have RGB value of
1208 mr,mg,mb in mask will be masked in the image.
1209 This is done by first finding an unused colour in the image,
1211 setting this colour as the mask colour and then using this
1212 colour to draw all pixels in the image who corresponding pixel
1213 in mask has given RGB value.
1214 The parameter mask is the mask image to extract mask shape from.
1216 It must have the same dimensions as the image.
1217 The parameters mr, mg, mb are the RGB values of the pixels in
1219 mask that will be used to create the mask.
1220 Return: Returns false if mask does not have same dimensions as
1222 the image or if there is no unused colour left. Returns true if
1223 the mask was successfully applied.
1224 Note: Note that this method involves computing the histogram,
1226 which is a computationally intensive operation.
1227 setOption(This, Name, Value) -> ok
1229 setOption(This, Name, Value) -> ok
1231 Types:
1233 This = wxImage()
1235 Name = Value = unicode:chardata()
1236 Sets a user-defined option.
1238 The function is case-insensitive to name.
1240 For example, when saving as a JPEG file, the option quality is
1242 used, which is a number between 0 and 100 (0 is terrible, 100 is
1243 very good).
1244 The lists of the currently supported options are in getOption/2
1246 and getOptionInt/2 function docs.
1247 See: getOption/2, getOptionInt/2, hasOption/2
1249 setPalette(This, Palette) -> ok
1251 Types:
1253 This = wxImage()
1255 Palette = wxPalette:wxPalette()
1256 Associates a palette with the image.
1258 The palette may be used when converting wxImage to wxBitmap (MSW
1260 only at present) or in file save operations (none as yet).
1261 setRGB(This, Rect, Red, Green, Blue) -> ok
1263 Types:
1265 This = wxImage()
1267 Rect =
1268 {X :: integer(),
1269 Y :: integer(),
1270 W :: integer(),
1271 H :: integer()}
1272 Red = Green = Blue = integer()
1273 Sets the colour of the pixels within the given rectangle.
1275 This routine performs bounds-checks for the coordinate so it can
1277 be considered a safe way to manipulate the data.
1278 setRGB(This, X, Y, R, G, B) -> ok
1280 Types:
1282 This = wxImage()
1284 X = Y = R = G = B = integer()
1285 Set the color of the pixel at the given x and y coordinate.
1287wxWidgets team. wx 2.1 wxImage(3)