Picture

From Real Software Documentation

Class (inherits from Object)

A Picture object contains a picture.

Properties

DebuggerMask	HorizontalResolution	RGBSurface
Depth	ImageCount	Transparent
Graphics	IndexedImage	VerticalResolution
HasAlphaChannel	Mask	Width
Height	Objects

Methods

ApplyMask	CopyOSHandle	Save
CopyMask	GetData

Shared Methods

FromData	IsImportFormatSupported
IsExportFormatSupported	Open

Constructors

Picture.Constructor(width as Integer, height as Integer)

Picture.Constructor(width as Integer, height as Integer, Depth as Integer)

Notes

Function	Parameters
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.

New Constructor

To create a Picture with an alpha channel, use the new constructor that omits the Depth parameter:

Constructor(width As Integer, height As Integer)

When this constructor is used, the Picture instance defaults to transparent and can be returned to that state using Graphics.ClearRect().

A picture created with the old constructor:

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

continues to default to having a white, opaque background. Calling Graphics.ClearRect on it retuns it to that state.

Updating “old” Pictures

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 ModernizePicture(input As Picture) As Picture
If input.hasAlphaChannel Then Return input

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

New Properties and Methods

HasAlphaChannel Property

HasAlphaChannel as Boolean

It 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 simply 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 Changes

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.

Pictures with alpha channels cannot use the "Transparent" property and attempting to assign anything other than zero to it will raise an UnsupportedOperationException at runtime. For pictures without alpha channels, this property will continue to work.

On Cocoa 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.

Pictures with alpha channels are supported on Cocoa, Windows (with GDI+ enabled), Linux, console applications, and Web Edition. On platforms without support for alpha channels, a PlatformNotSupportedException]] is raised when trying to create the Picture.

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 Mac OS X, 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 32-bit ARGB buffer wrapped by a GDI+ GpBitmap. Note: the ARGB buffer is NOT premultiplied. This buffer can be accessed the same way as for masked images: REALLockPictureDescription and then GdipBitmapLockBits (you are responsible for calling GdipBitmapUnlockBits).

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 applications and Web Edition, 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 Editor, by calling the Picture constructor or the OpenAsVectorPicture 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. If you specify a depth of zero, Real Studio creates 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.

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
dim width as integer = 2000
dim height as integer = 2000

// creates new picture
dim pic as new Picture(width, height, 32)

// fill with red
pic.Graphics.ForeColor = &cFF0000
pic.Graphics.FillRect 0,0,100,100

// and show picture in a window/canvas backdrop
Backdrop = pic

Exception o as OutOfMemoryException
MsgBox "Picture dimensions too big."+EndOfLine+EndOfLine+str(width*height*4/1024/1024)+" MB"

Picture objects have no events.

Using the Transparent property with “old” Pictures

The Transparent property works for pictures that lack an alpha channel only if making the color white transparent produces the desired effect. In the example shown below, the picture’s interior is white but its border is black. Making the white “layer” transparent makes the white area transparent. Notice that only the interior is white, but the border is not.

No Transparency: Transparent=0.

Transparency: Transparent=1.

In many cases, you need to work with the Mask property. For example, if you have a picture, myPicture, and a custom mask, myMask, stored in the Project Editor, the code:

myPicture.Mask.Graphics.DrawPicture myMask,0,0

will assign the custom mask to the Mask property of myPicture.

Obviously, you should upgrade these pictures so that they support alpha channel information. Use code such as this to convert the pictures:

Function ModernizePicture(input as Picture) as Picture
if input.hasAlphaChannel then return input

dim result as new Picture( input.width, input.height )
result.graphics.drawPicture( input, 0, 0 )
return result
End Function

Class Constants

Save can save in BMP, JPEG, and PNG on all platforms. Beyond that, the Save shared method has second parameter that enables you to specify the format in which the picture will be saved. Formats in the range of 0-99 are reserved for meta-formats. Meta-formats map to a various concrete formats based on the target, the data being saved, or other criteria (The mappings may change in future versions of Real Studio).

The numbers:

100-199 are reserved for formats that are supported on multiple platforms (currently none).
200-299 are reserved for formats that are supported on the Macintosh.
300-399 are reserved for formats supported on Windows.
x00-x49 are vector formats
x50-x99 are raster formats

Meta-Formats

Value	Class Constant	Compatibility	Description
0	SaveAsMostCompatible	MostCompatible	Most widely-used format for the platform. Mac = PICT Win32 = BMP)
1	SaveAsMostComplete	MostComplete	Format most likely to retain all vector info. Mac = PICT Win32 = EMF)
2	SaveAsDefault	Default	DefaultVector or DefaultRaster, depending on picture data. Mac = PICT Win32 vector=EMF Win32 raster= BMP
3	SaveAsDefaultVector	DefaultVector	Platform's standard vector format. Mac = PICT Win32 = EMF)
4	SaveAsDefaultRaster	DefaultRaster	Platform's standard raster format. Mac = Raster PICT Win32 = BMP)

Mac-only Formats

Value	Class Constant	Format	Description
100	SaveAsMacintoshPICT Introduced 2008r4	PICT	Macintosh PICTs are "type 2" PICTs that are saved with the full resolution of the image. Includes simple vector data. The PICT format has been deprecated by Apple; use JPEG or PNG on Macintosh instead.
250	SaveAsMacintoshRasterPICT Introduced 2008r4	RasterPICT	Flattens all vector data to pixels.

Windows & Cross-Platform Formats

Value	Class Constant	Format	Description
150	SaveAsPNG	PNG	Portable Network Graphics. Supported on Windows only if GDI+ is installed.
151	SaveAsJPEG	JPEG	Joint Photographics Expert Group. Supported on Windows only if GDI+ is installed.
300	SaveAsWindowsWMF	WMF	Windows Metafile format (old vector format).
301	SaveAsWindowsEMF	EMF	Extended Metafile format (newer vector format).
350	SaveAsWindowsBMP	BMP	Windows bitmap format.
402	SaveAsGIF	GIF	Graphics Interchange Format. Supported on Windows only if GDI+ is installed.
403	SaveAsTIFF	TIFF	Tag Image File Format. Supported on Windows only if GDI+ is installed.

Cross-Platform Formats

These formats are cross-platform: SaveAsPNG, SaveAsJPEG, SaveAsWindowsBMP, SaveAsGIF, SaveAsTIFF. On Windows, these formats require GDI+; if it is not available, Real Studio will try to use QuickTime.

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
QualityMax	100
QualityMedium	50
QualityMin	0