Class

Picture

Description

A Picture object contains a Picture or an image.

Methods

Name

Parameters

Returns

Shared

ApplyMask

theMask As Picture

BestRepresentation

width As Integer, height As Integer, scale As Double

Picture

Constructor

width As Integer, height As Integer

Constructor

width As Integer, height As Integer, depth As Integer

Constructor

width As Integer, height As Integer, bitmaps() As Picture

CopyColorChannels

Picture

CopyMask

Picture

CopyOSHandle

type As HandleType

Ptr

width As Integer, height As Integer, scale As Double, type As HandleType

Ptr

FromData

data As MemoryBlock

Picture

✓

data As String

Picture

✓

FromHandle

image As Ptr

Picture

✓

ImageAt

index As Integer

Picture

IsExportFormatSupported

format As Formats

Boolean

✓

IsImportFormatSupported

format As Formats

Boolean

✓

Open

file As FolderItem

Picture

✓

OpenVector

vectorFile As FolderItem

Picture

✓

Save

file As FolderItem, format As Formats, quality As Integer = Picture.QualityDefault

SystemImage

name As String, size As Double, weight As Picture.SystemImageWeights = Picture.SystemImageWeights.Regular, templateColor As ColorGroup = Nil, fallbackTemplateImage As Picture = Nil

Picture

✓

name As String, weight As Picture.SystemImageSizes = Picture.SystemImageSizes.dp24, templateColor As Color = &c000000

Picture

✓

ToData

format As Formats, jpegQuality As Integer = Picture.QualityDefault

MemoryBlock

Enumerations

Picture.Formats

Formats

The various Picture formats that are supported.

Enum

Supported Platforms

BMP

Android, Linux, Mac, Windows

GIF

Android, Mac, Windows

HEIF

Android

JPEG

Android, iOS, Linux, Mac, Windows

PNG

Android, iOS, Linux, Mac, Windows

TIFF

iOS, Linux, Mac, Windows

WebP

Android

Picture.HandleType

HandleType

OS handle types.

Enum

Description

MacCGImage

A CGImageRef that you are responsible for releasing with CFRelease. Supported in macOS GUI applications.

WindowsBMP

A 32-bit HBITMAP that you are responsible for releasing with DeleteObject. Supported in Windows GUI applications.

WindowsICON

A 32-bit HICON that you are responsible for releasing with DeleteObject. Supported in Windows GUI applications.

LinuxGdkPixbuf

A 32-bit GdkPixbuf that you are responsible for releasing with g_object_unref. Supported in Linux GUI applications.

ConsoleGDImage

A gdImagePtr that you are responsible for releasing with gdFree. This requires the use of the libgd library. Supported in console applications (all platforms).

MacNSImage

A NSImage object that has been autoreleased, so an explicit release is not necessary. This is supported for all types of Pictures, including vector images. Supported in macOS GUI applications.

iOSUIImage

A UIImage object that has been autoreleased, so an explicit release is not necessary. Supported in iOS/iPadOS applications.

Picture.SystemImageSizes

SystemImageSizes

The size of a system image retrieve using SystemImage method.

Enum

Description

dp18

18 display points

dp24

24 display points

dp36

36 display points

dp48

48 display points

Picture.SystemImageWeights

SystemImageWeights

The weight of a system image retrieve using SystemImage method.

Enum

Description

Unspecified

An unspecified symbol image weight.

UltraLight

An ultralight weight.

Thin

A thin weight.

Light

A light weight.

Regular

A regular weight.

Medium

A medium weight.

Semibold

A semibold weight.

Bold

A bold weight.

Heavy

A heavy weight.

Black

An ultra-heavy weight.

Picture.Types

Types

The valid Picture types: Image, Vector, MutableBitmap, ImmutableBitmap

Enum

Description

Image

An Image for use with HiDPI displays.

Vector

A Vector graphic.

MutableBitmap

A bitmap image that can be modified.

ImmutableBitmap

A bitmap image that cannot be modified.

Property descriptions

Picture.Depth

Depth As Integer

The bit depth of the picture.

This property is read-only.

Important

This property is not supported for mobile projects.

Picture.Graphics

Graphics As Graphics

The actual Picture. The Graphics property gives you access to the methods of the Graphics class. Use it to draw in the Picture. Use it when you need to draw into the Picture. Create a new Picture instance and then draw into it using the Graphics property.

This property is read-only.

This example creates a blank Picture instance and then draws into it using the Graphics property. It assigns the Picture to the backdrop property of a Canvas. A recommended alternative is to update the interface via drawing in the Canvas's Paint event instead.

Var p As New Picture (340, 280, 32)

p.Graphics.Bold = True
p.Graphics.Italic = True
p.Graphics.FontName = "Helvetica"
p.Graphics.FontSize = 18
p.Graphics.DrawingColor = &cff0000
p.Graphics.DrawText("Hello World", 10, 100)

Canvas1.Backdrop = p

You can also draw into an existing Picture instance. However, in this case, because loading a picture from a file creates a picture that is immutable (not changeable), you must create another picture and draw the picture you are opening from a file into that picture so that you can draw on top of it:

Var p As Picture
Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("image/jpeg")
If f <> Nil Then
  p = Picture.Open(f)
  Var mutablePicture As New Picture(p.Width, p.Height)
  mutablePicture.Graphics.Bold = True
  mutablePicture.Graphics.Italic = True
  mutablePicture.Graphics.FontName = "Helvetica"
  mutablePicture.Graphics.FontSize = 18
  mutablePicture.Graphics.DrawingColor = &cff0000
  mutablePicture.Graphics.DrawText("Hello World", 50, 230)
  Canvas1.Backdrop = mutablePicture
End If

Picture.Handle

Handle As Ptr

Returns a Ptr to the underlying image. This property is for use with Declares on iOS only.

The Ptr returned is a UIImage.

Important

This property is not supported for Android.

Note

A Ptr is only returned if the picture is a project item or was retrieved via Picture.SystemImage.

This property is read-only.

Picture.HasAlphaChannel

HasAlphaChannel As Boolean

True if the Picture has an alpha channel.

This property is read-only.

Important

This property is not supported for mobile projects.

A Picture that is created with the constructor that omits the Depth parameter has an alpha channel and old pictures can be converted to this format with the following code:

Function ConvertToAlphaPicture(input As Picture) As Picture
    If input.HasAlphaChannel Then Return input

    Var result As New Picture(input.Width, input.Height)
    result.Graphics.DrawPicture(input, 0, 0)
    Return result
  End Function

Picture.Height

Height As Integer

The height (in pixels) of the Picture.

This property is read-only.

This example displays the width and height of the Picture that the user chose:

Var pic As Picture
Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("image/jpeg")
If f <> Nil Then
  pic = Picture.Open(f)
  Label1.Text = pic.Width.ToString
  Label2.Text = pic.Height.ToString
End If

Picture.HorizontalResolution

HorizontalResolution As Integer

The horizontal resolution of the Picture.

Important

This property is not supported for Android.

The horizontal resolution is established when you use the Open shared method and written out when using the Save method. When creating a Picture, the default resolution is 72 (pixels).

Note

To get the actual Picture resolution for an opened Picture file on Linux, gtk+ 2.32 or later is required.

This example gets the horizontal and vertical resolution of the Picture that was opened:

Var pic As Picture
Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("image/jpeg")
If f <> Nil Then
  pic = Picture.Open(f)
  ImageWell1.Image = pic
  Label1.Text = pic.HorizontalResolution.ToString
  Label2.Text = pic.VerticalResolution.ToString
End If

Picture.ImageCount

ImageCount As Integer

The number of indexed images in the Picture.

This property is read-only.

Important

This property is not supported for Android.

This applies to image formats that can contain multiple images, such as TIFF.

This example gets the number of indexed images in the Picture.

Var width As Integer = 2000
Var height As Integer = 2000

' creates new picture
Var pic As New Picture(width, height, 32)
Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("image/jpeg")
If f <> Nil Then
  pic = Picture.Open(f)
  ImageWell1.Image = pic
  Label1.Text = pic.ImageCount.ToString
End If

Picture.Objects

Objects As Group2D

A set of vector graphics associated with the Picture (optional).

Important

This property is not supported for mobile projects.

Specify a depth of zero to create a Picture with no pixel map at all, but with a preinitialized Objects property. Use this option for creating vector graphics pictures via the set of Object2D subclasses.

Create a vector image:

Var vectorImage As New Picture(10, 10, 0)

Picture.RGBSurface

RGBSurface As RGBSurface

Provides pixel-level access to the Picture's bitmap.

This property is read-only.

Used only for pictures built with the Picture constructor with no pixel depth or only a depth of 16 or 32, otherwise it returns Nil. Returns an RGBSurface object. Calling RGBSurface is a computer-intensive process. Use it to access individual pixels of the Picture image. It is extremely fast — faster than accessing pixels through the Graphics property.

Picture.Type

Type As Types

The Type of the Picture. This is set automatically based on how the Picture was created.

This property is read-only.

Important

This property is not supported for Android.

Uses the Types Enumeration to specify the Type:

  • Image: An Image for use with HiDPI displays.

  • Vector: A Vector graphic.

  • MutableBitmap: A bitmap Picture that can be modified.

  • ImmutableBitmap: A bitmap Picture that cannot be modified.

Pictures in the project, loaded from disk, received from drag and drop, or loaded from data will be loaded as Images (unless it's a Vector in which case it is loaded as Vector). This better preserves color spaces, loads multiple resolutions if the format supports it, and reduces memory usage.

Picture.VerticalResolution

VerticalResolution As Integer

The vertical resolution of the Picture.

Important

This property is not supported for Android.

The vertical resolution is established when you use the Open shared method and written out when you use the Save method. When creating a Picture, the default resolution is 72 (pixels).

Note

To get the actual Picture resolution for an opened Picture file on Linux, gtk+ 2.32 or later is required.

This example gets the horizontal and vertical resolution of the Picture that was opened.

Var pic As Picture
Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("image/jpeg")
If f <> Nil Then
  pic = Picture.Open(f)
  ImageWell1.Image = pic
  Label1.Text = pic.HorizontalResolution.ToString
  Label2.Text = pic.VerticalResolution.ToString
End If

Picture.Width

Width As Integer

The width (in pixels) of the Picture.

This property is read-only.

This example displays the width and height of the Picture that the user chose.

Var width As Integer = 2000
Var height As Integer = 2000

' creates new picture
Var pic As New Picture(width, height)
Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("image/jpeg")
If f <> Nil Then
  pic = Picture.Open(f)
  Label1.Text = pic.Width.ToString
  Label2.Text = pic.Height.ToString
End If

Method descriptions

Picture.ApplyMask

ApplyMask(theMask As 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.

Important

This method is not supported for Android.

Picture.BestRepresentation

BestRepresentation(width As Integer, height As Integer, scale As Double) As Picture

Calculates which Picture is the best to use for drawing at the requested size.

Important

This method is not supported for Android.

The algorithm iterates through the indexed images, first finding Picture with the closest number of pixels to the destination, preferring the next largest image if no exact match is found. If multiple pictures match, the Picture with the DPI closest to the destination scale is chosen. It is possible that this function returns Self.

Raises an InvalidArgumentException if width, height, or scale are less than or equal to zero.

Picture.Constructor

Constructor(width As Integer, height As Integer)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a picture of the width and height specified.

A Picture created with this constructor supports an alpha channel directly instead of requiring the use of masks.

The width and height are in points.

Picture.Constructor

Constructor(width As Integer, height As Integer, depth As Integer)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a picture of the size specified by the width, height with the depth specified. The width and height are in points.

Important

This method is not supported for mobile projects.

A Picture created with this constructor supports an alpha channel directly instead of requiring the use of masks.

Picture.Constructor

Constructor(width As Integer, height As Integer, bitmaps() As Picture)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a Picture of the size specified by the width and height from one or more Bitmap pictures.

Important

This method is not supported for Android.

The width and height are in points. The bitmaps are copied upon creation. All bitmaps must have the same aspect ratio. A bitmap's DPI will be calculated from the point size and the bitmap's size in pixels. Pictures created using this constructor have their Type set to Types.Image.

Picture.CopyColorChannels

CopyColorChannels As Picture

Copies just the color information from a Picture.

Important

This method is not supported for Android.

This method returns a clone of the color data in a Picture with a solid mask.

The returned Picture object:

  • has the same dimensions, resolutions and scale factors as the original.

  • is a mutable bitmap

  • uses alpha channels instead of masks (i.e. HasAlphaChannel will be True)

  • is entirely opaque

Warning

An UnsupportedOperationException will be raised when called on a vector or multi-representation image.

Warning

An OutOfMemoryException will be raised if the Picture cannot be created.

Get the color channels from MyPic:

Var colorChannels As Picture
colorChannels = MyPic.CopyColorChannels

Picture.CopyMask

CopyMask As Picture

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.

Important

This method is not supported for Android.

Picture.CopyOSHandle

CopyOSHandle(type As Picture.HandleType) As Ptr

Returns a platform-specific image handle.

Important

This method is not supported for Android.

The following code gets the CGImageRef from the Picture and properly releases it.

Declare Sub CFRelease Lib "CoreFoundation" (obj As Ptr)

Var pict As New Picture(100, 100, 32)
Var cgImage As Ptr = pict.CopyOSHandle(Picture.HandleType.MacCGImage)
' Do something with the 'cgImage' object
CFRelease(cgImage)

Picture.CopyOSHandle

CopyOSHandle(width As Integer, height As Integer, scale As Double, type As HandleType) As Ptr

Returns a platform-specific image handle that is the best match for drawing at the given resolution, using the same logic as BestRepresentation.

Important

This method is not supported for Android.

Picture.ImageAt

ImageAt(index As Integer) As Picture

Returns the image in the picture specified by the passed index.

Important

This method is not supported for Android.

Warning

The individual pictures aren't necessarily stored/returned in ascending scalefactor order. Do not rely on a particular order for the pictures.

This example gets the image referenced by the passed index and displays it in the ImageViewer:

Var pic As Picture
Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("image/jpeg")
If f <> Nil Then
  pic = Picture.Open(f)
  ImageViewer1.Image = pic.ImageAt(0)
End If

If you have an Image Set with multiple images for HiDPI and want to split out each of the pictures it contains, you can do so like this:

Var g As Graphics
Var p, pics() As Picture

' Break the Image into its component pictures
' Also copy the horizontal/vertical resolution and scale factors
' so that the pictures draw properly when used later.
For i As Integer = 0 To MyImageSet.ImageCount - 1
  p = New Picture(MyImageSet.ImageAt(i).Width, ImageAt(i).Height)
  p.HorizontalResolution = MyImageSet.IndexedImage(i).HorizontalResolution
  p.VerticalResolution = MyImageSet.IndexedImage(i).VerticalResolution
  pics.Add(p)
  g = p.Graphics
  g.ScaleX = p.HorizontalResolution / 72
  g.ScaleY = p.VerticalResolution / 72
  g.DrawPicture(MyImageSet.ImageAt(i), 0, 0)
Next

If you later modify the pictures in the array and want to recreate it as an image, you can do so using the constructor like this:

' Recreate the image from the component pictures
p = New Picture(MyImageSet.Width, MyImageSet.Height, pics)

Picture.FromData

FromData(data As MemoryBlock) As Picture

Obtains a Picture that is stored in a MemoryBlock and returns a Picture.

This method is shared.

This example uses ToData to convert an image in an ImageViewer into a MemoryBlock and then uses FromData to display the image:

Var mb As MemoryBlock
If ProductImageWell.Image <> Nil Then
  ' Get the image data
  mb = ProductImageWell.Image.ToData(Picture.Formats.JPEG, Picture.QualityHigh)
  ' convert the memoryblock back into an image
  ImageViewer.Image = Picture.FromData(mb)
End If

Picture.FromData

FromData(data As String) As Picture

Obtains a Picture that is stored in the data passed and returns a Picture.

This method is shared.

Important

This signature is supported for Android only.

Picture.FromHandle

FromHandle(image As Ptr) As Picture

Returns a Picture from an OS handle

This method is shared.

Important

This method is supported for iOS only.

Picture.IsExportFormatSupported

IsExportFormatSupported(format As Formats) As Boolean

Returns True if the passed format is supported for export.

This method is shared.

Important

This method is supported for desktop and console projects only.

This example checks to see that the format is supported for export prior to calling it:

Var imageData As String
Var bs As BinaryStream
Var f As FolderItem
If ImageWell1.Image <> Nil Then
  ' Get a temporary file to save the image to
  If Picture.IsExportFormatSupported(Picture.Formats.JPEG) Then
    f = SpecialFolder.Temporary.Child("TempImage.jpg")

    ' Save the image out to the file
    ImageWell1.Image.Save(f, Picture.Formats.JPEG)
  End If

  ' Open the file as a BinaryStream and read the data in
  bs = BinaryStream.Open(f, False)
  If bs <> Nil Then
    imageData = bs.Read(bs.Length)
    bs.Close
  End If

  ' delete the temporary file if it exists
  If f.Exists Then
    f.Delete
  End If
End If

Picture.IsImportFormatSupported

IsImportFormatSupported(format As Formats) As Boolean

Returns True if the passed format is supported for import.

This method is shared.

Important

This method is supported for desktop and console projects only.

BMP, GIF and TIFF formats are not supported for Console apps.

This example checks to see if a format is supported for import prior to calling it:

Var width As Integer = 2000
Var height As Integer = 2000

' creates new picture
Var pic As New Picture(width, height)

Var picFile As FolderItem
picFile = FolderItem.ShowOpenFileDialog("image/jpeg")
If Picture.IsImportFormatSupported(Picture.Formats.JPEG) Then
  If f <> Nil Then
    pic = Picture.Open(picFile)
    ImageWell1.Image = pic
  End If
End If

Picture.Open

Open(file As FolderItem) As Picture

Opens the passed FolderItem to be read as a Picture. Returns a Picture on success. If the FolderItem passed is nil, a NilObjectException is raised. If Picture.Open fails for any other reason, Nil is returned with no other error information.

This method is shared.

Note

Pictures opened with this method are immutable.

The following example prompts you to select a file and then opens it and displays it in an DesktopImageViewer:

Var picFile As FolderItem
picFile = FolderItem.ShowOpenFileDialog("")

If picFile <> Nil And picFile.Exists Then
  Var pic As Picture
  pic = Picture.Open(picFile)
  ImageWell1.Image = pic
End If

Picture.OpenVector

OpenVector(vectorFile As FolderItem) As Picture

Opens the passed FolderItem to be read as a vector Picture.

This method is shared.

Important

This method is supported for desktop and console projects only.

It will do its best to convert a PICT file (on macOS) or an .emf file (Windows) to a Picture composed of Object2D objects. The original file may contain elements that do not have an equivalent Object2D object. This method will do its best to map these objects, but there may be some loss of information, depending on the characteristics of the original file. PICTs support unrotated Rectangles, Lines, Ellipses, RoundRects, Polygons, Text, Pixmaps, and Arcs.

.emf files support unrotated Rectangles, Lines, Ellipses, RoundRects, Polygons, Text, Pixmaps and Arcs.

.emf files are displayed as actual size. For the most part this is huge; you probably will want to scale them down before viewing (pic1.objects.scale = scalingFactor). We find that a scale factor of 0.045 is a good value.

The following example opens an ancient PICT file as a Picture. The image/x-pict file type has been added using the File Types Editor.

Var f As FolderItem

f = FolderItem.ShowOpenFileDialog("image/x-pict")
Var p As Picture

p = Picture.OpenVector(f)
If p <> Nil Then
  MessageBox(p.ImageCount.ToString)
Else
  MessageBox("Open failed!")
End If

Picture.Save

Save(file As FolderItem, format As Formats, quality As Integer = Picture.QualityDefault)

Saves the Picture in file specified by file, using the file format specified by format. For the list of available formats, see Formats.

Note

Only JPEG and PNG are supported in console applications

If the FolderItem exists, then it will be overwritten by the new Picture file.

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. Introduced 2010r5

Constant

Value

QualityDefault

-1

QualityMaximum

100

QualityHigh

80

QualityMedium

50

QualityLow

25

QualityMinimum

0

The following example saves the contents of an DesktopImageViewer to a temporary file on disk and then reads it into a BinaryStream for storage in a database. The property f as FolderItem is a property of the window.

Var imageData As String
Var bs As BinaryStream
Var f As FolderItem
If ImageWell1.Image <> Nil Then
  ' Get a temporary file to save the image to
  If Picture.IsExportFormatSupported(Picture.Formats.JPEG) Then
    f = SpecialFolder.Temporary.Child("TempImage.jpg")

    ' Save the image out to the file
    ImageWell1.Image.Save(f, Picture.Formats.JPEG)
  End If

  ' Open the file as a BinaryStream and read the data in
  bs = BinaryStream.Open(f, False)
  If bs <> Nil Then
    imageData = bs.Read(bs.Length)
    bs.Close
  End If

  ' delete the temporary file if it exists
  If f.Exists Then
    f.Delete
  End If
End If

Picture.SystemImage

SystemImage(name As String, size As Double, weight As SystemImageWeights = Picture.SystemImageWeights.Regular, templateColor As ColorGroup = Nil, fallbackTemplateImage As Picture = Nil) As Picture

This method retrieves an image based upon the parameters passed.

On iOS these images come from iOS itself and are called SF Symbols. There are over more than 1500 system symbol images available. To browse the available symbol images, use the Apple SF Symbols viewer app.

This method is shared.

Important

This method is only supported for iOS.

This example returns the image named "moon" at a size of 50 and then draws it into a Graphics object:

Var moon As Picture = Picture.SystemImage("moon", 50)
g.DrawPicture(moon, 0, 0)

Picture.SystemImage

SystemImage(name As String, weight As Picture.SystemImageSizes = Picture.SystemImageSizes.dp24, templateColor As Color = &c000000) As Picture

This method retrieves an image based upon the parameters passed.

On Android, the image comes from a library of images built-in to the Xojo Android framework. There are over more than 2000 images available.

Sizes 18, 24, 36 and 48 are supported for Android.

This method is shared.

Important

This method is only supported for Android.

This example returns the image named "moon-full" at a size of 48 and then draws it into a Graphics object:

Var moon As Picture = Picture.SystemImage("moon-full", Picture.SystemImageSizes.dp48)
g.DrawPicture(moon, 0, 0)

Picture.ToData

ToData(format As Formats, jpegQuality As Integer = Picture.QualityDefault) As MemoryBlock

Converts the Picture to a MemoryBlock.

Of the value formats, BMP, GIF and TIFF and not supported for Console apps.

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 instead of the literal values.

Constant

Value

QualityDefault

-1

QualityMaximum

100

QualityHigh

80

QualityMedium

50

QualityLow

25

QualityMinimum

0

This example uses ToData to convert an image in an DesktopImageViewer into a MemoryBlock:

Var mb As MemoryBlock
If productImageWell.Image <> Nil Then
  ' Get the image data
      mb = ProductImageWell.Image.ToData(Picture.Formats.JPEG, Picture.QualityHigh)

  ' convert the memoryblock back into an image
  Imagewell2.Image = Picture.FromData(mb)
End If

Notes

Note

Console applications only support JPEG and PNG image types.

Image sets and hidpi

When adding Pictures to your projects, you create Image Set Editor which can contain the Picture at various sizes for use with HiDPI displays.

Also refer to 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: Color.RGB, Color.HSV, Color.CMY, and &c. These functions have an optional fourth parameter that specifies the degree of transparency of the color. Here are the modified functions:

Function

Parameters

Color.RGB

red as Integer

Color.HSV

hue as Double

Color.CMY

cyan as Double

&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:

Function ConvertToAlphaPicture(input As Picture) As Picture
  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)
  Return result
End Function

HasAlphaChannel property

HasAlphaChannel As Boolean

This property indicates whether or not the Picture has an alpha channel. For Pictures using masks, this returns False.

Copymask method

CopyMask As Picture

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.

Applymask method

ApplyMask(theMask As 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.

Plugin support

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:

' 2000 x 2000 Pixel works, but 20000 x 20000 Pixel will raise 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")

Cross-platform formats

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.

Constant

Value

QualityDefault

1

QualityHigh

80

QualityLow

25

QualityMaximum

100

QualityMedium

50

QualityMinimum

0

Compatibility

All project types on all supported operating systems.

See also

Object parent class; RGBSurface object; Graphics class.