From Xojo Documentation
|You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!|
A Picture object contains a picture or an image.
|Console applications only support JPEG and PNG image types.|
Image Sets and HiDPI
When adding Pictures to your projects, you create UserGuide:Image Set Editor which can contain the picture at various sizes for use with HiDPI displays.
Also refer to UserGuide:HiDPI_Support for important additional information.
Support for Transparency
Picture objects support alpha channels (transparency) directly, without the need for a mask.
Support for the alpha channel is now built into the color functions: RGB, HSV, CMY, and &c. These functions have an optional fourth parameter that specifies the degree of transparency of the color. Here are the modified functions:
|RGB||red as Integer|
green as Integer
blue as Integer
alpha as Integer = 0
|HSV||hue as Double|
saturation as Double
value as Double
alpha as Integer = 0
|CMY||cyan as Double|
magenta as Double
yellow as Double
alpha as Integer = 0
|&c||RRGGBBAA, where the hex digits specify the amounts of red, green, blue, and transparency in the color. For the transparency parameter, 00 is opaque and FF is fully transparent.|
In the Picture class, support for alpha channels means that the use of masks is no longer required. This streamlines the process and reduces memory support. To take advantage of this feature, you can create new Picture objects with alpha channel support and convert “old” picture objects to those with alpha channels.
Updating Pictures with Masks
Pictures loaded from disk, databases, project files, or Picture.FromData continue to return pictures with masks. This is required for legacy compatibility, but masked Pictures can be converted to a Picture with an alpha channel with the following code:
If input.hasAlphaChannel Then Return input
Var result As New Picture(input.Width, input.Height)
result.HorizontalResolution = input.HorizontalResolution
result.VerticalResolution = input.VerticalResolution
result.Graphics.DrawPicture(input, 0, 0)
New Properties and Methods
This property indicates whether or not the Picture has an alpha channel. For Pictures using masks, this returns False.
When used on a picture with an alpha channel, this takes the image's alpha channel and creates the equivalent mask. If used on a picture with a mask, it returns a copy of the current mask. In neither case does it alter the original image and the copied mask is not updated when any drawing happens on the original Picture.
When used on a Picture with an alpha channel, this overwrites the Picture's alpha channel with the mask data. When used on a picture with a mask, it overwrites the current mask with a copy of the mask passed in.
Other Alpha Channel Notes
Pixel and RGBSurface have been updated to properly support alpha channels by taking them into account when rendering them. Additionally, Pixel properly reports back alpha channel information, if available.
Pictures with alpha channels cannot also use masks. Trying to do so will raise an UnsupportedOperationException at runtime. Reading this value always returns Nil for pictures with alpha channels. For pictures without alpha channels, the mask functionality continues to work normally.
On Mac and Linux, Pictures are stored internally with their alpha channels premultiplied into the color channels. Since premultiplication is a lossy operation, the color you draw may not be exactly what you get out when inspecting it with an RGBSurface. For example, drawing a &cFF00EECC rectangle will result in a different color if read from that pixel using RGBSurface.
The color type has changed from being XRGB to ARGB. If you previously put garbage into the first byte, this is going to cause problems now that the framework uses this to store the alpha component.
On macOS, a Picture with an alpha channel is represented internally as a premultiplied ARGB buffer wrapped by a CGBitmapContext. This buffer can be accessed the same way as for masked images: REALLockPictureDescription and then CGBitmapContextGetData.
On Windows, a Picture with an alpha channel is represented internally as a premultiplied 32-bit BGRA buffer. This buffer can be accessed the same way as for masked images: REALLockPictureDescription and the raw bytes are returned in the data field.
On Linux, a Picture with an alpha channel is represented internally as a 32-bit premultiplied ARGB buffer wrapped by a cairo_t. This buffer can be accessed the same way as for masked images: REALLockPictureDescription and then cairo_image_surface_get_data( cairo_get_target( cairo_t * ) ).
On console and web apps, a Picture with an alpha channel is represented internally as a 32-bit ARGB buffer wrapped by a gdImagePtr. Note: the ARGB buffer is NOT premultiplied, and the maximum alpha value is 127 instead of 255. This buffer can be accessed the same way as for masked images: REALLockPictureDescription with pictureGDPtr (this will give you the raw buffer with an 11 byte header).
Creating a Picture
A Picture object is created by adding a picture to the project, by calling the Picture constructor or the OpenVector method of a FolderItem object. When you use the New operator, you must use the constructor. If you use the New operator but run out of memory, an OutOfMemoryException error will be raised.
Here is an example on how to create a picture and handle the OutOfMemoryException exception:
Var width As Integer = 2000
Var height As Integer = 2000
// creates new picture
Var pic As New Picture(width, height)
// fill with red
pic.Graphics.DrawingColor = &cFF0000
pic.Graphics.FillRectangle(0, 0, 100, 100)
// and show picture in a window/canvas backdrop
Self.Backdrop = pic
Exception o As OutOfMemoryException
MessageBox("Picture dimensions too big." + EndOfLine + EndOfLine + Integer(width * height * 4 / 1024 / 1024).ToString + " MB")
PNG, JPEG and BMP formats are cross-platform.
Unrecognized formats or formats not supported for the built target will result in an UnsupportedFormatException. The Message property of the exception will contain additional information about what went wrong.
JPEG Quality Constants
If you are using the JPEG format, then there is an optional parameter for the quality of the JPEG. You specify the quality using the following class constants.