Classes and functions for extending TFPImageCanvas.

lazcanvas.pas contains classes and functions for extending TFPImageCanvas to support more stretching filters, and to support all features from the LCL TCanvas. TLazCanvas also fixes various small problems and incompatibilities between TFPImageCanvas versions, making the interface smoother and more consistent.

Do not use anything from the LCL here, as this unit should be kept strictly independent. LCLProc.pas is allowed for DebugLn, but only during debugging or profiling.

Author: Felipe Monteiro de Carvalho

Identifies image formats supported in TLazCanvas.

Used in the implementation of the CanvasCopyRect method in TLazCanvas, and in custom-drawn LCL controls to speed up image drawing in the LCL interface.

Images use a format other than those in this enumeration. Images use 16-bit RGB colors. Images use 24-bit RGB colors. Images use 24-bit RGB colors with inverse values. Images use 24-bit BGR colors. Images use 32-bit BGR colors with an Alpha channel. Images use 32-bit RGB colors with an Alpha channel. Images use 32-bit RGB colors with an Alpha channel in the low-order octet. Implements a very sharp and square interpolation.

TFPSharpInterpolation implements a very sharp and square interpolation for stretching, similar to StretchBlt from the Windows API.

Paints an image on the Canvas using the specified coordinates and dimensions. Horizontal coordinate. Vertical coordinate. Width for the output. Height for the output. Contains properties reflecting the state for a Lazarus canvas.

TLazCanvasState is a class with public members that reflect the state for a TLazCanvas instance. A destructor is provided to ensure that resources allocated to members variables are freed before the class instance is destroyed.

Instances of TLazCanvasState are created, stored, and retrieved using an internal list in TLazCanvas in its SaveState and RestoreState methods.

Brush for the canvas. Pen for the canvas. Font for the canvas. Base window origin for the canvas.

The values in WindowOrg are relative to the coordinates in BaseWindowOrg. BaseWindowOrg coordinates are relative to the canvas for the containing Form. It is useful when implementing the non-native windowed controls.

Window origin for the canvas.

Contains the absolute coordinates for the canvas with BaseWindowOrg summed up.

Indicates if Clipping is enabled for the canvas. Defines the clipping region for the canvas. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that resources allocated for the Brush and Pen properties are freed before the class instance is destroyed. Destroy calls the inherited destructor prior to exiting from the method.

Implements a canvas which masks differences between FCL and LCL canvas classes.

TLazCanvas is an FCL TFPImageCanvas descendant. TLazCanvas extends the ancestor class to support stretching filters and features found in the TCanvas class from the LCL. TLazCanvas also fixes various small problems and incompatibilities between TFPImageCanvas versions, making the interface smoother and more consistent.

TLazCanvas is used in the implementation of custom-drawn widgetset classes, and provides a device context used to perform drawing operations for a control.

There are several useful examples using TLazCanvas on the Lazarus Wiki at:

Developing with Graphics

TCanvas Stores saved canvas state information.

Used to store and restore canvas states in the SaveState and RestoreState methods. Contains TLazCanvasState class instances.

Gets the value for the AssignedBrush property. Value for the AssignedBrush property. Gets the value for the AssignedPen property. Value for the AssignedPen property. Gets the value for the AssignedFont property. Value for the AssignedFont property. Gets the value for the WindowOrg property. Value for the WindowOrg property. Sets the value for the WindowOrg property. New value for the WindowOrg property. Sets the color for the pixel at the specified coordinates. Horizontal pixel coordinate. Vertical pixel coordinate. Color for the pixel. Creates the custom font used as the default for the canvas.

DoCreateDefaultFont is an overridden TFPCustomFont function used to provide the default font for the canvas class instance. DoCreateDefaultFont implements the abstract virtual method defined in an ancestor class, and emulates the method defined in TCanvas.

DoCreateDefaultFont sets the Size property in the font to zero (0); this causes the default font size for the platform or widget set to be used. The FPColor property in the font is set to colBlack.

TFPCustomFont instance created and initialized in the method. Adjusts the fcl-image coordinate system to be compatible with coordinates used in TCanvas.

Adjusts the values in Bounds to use the coordinate system in TCanvas, and draws borders using the style and/or pattern in the Pen for the canvas.

DoRectangleFill is used to optimize and fill a rectangle area.

TRect with the bounds for the rectangular area. Adjusts the FCL image rectangle to be LCL compatible and draws a filled rectangle on the canvas.

DoRectangleFill adjusts the fcl-image coordinate system to be compatible with coordinates used in TCanvas.

It calls the FCL SortRec routine (in clipping.pp) to normalize the values in Bounds prior to the drawing operation. It also shrinks the rectangle by a single pixel on the bottom and right edges for the border drawn in the Rectangle method. The original values in Bounds are not changed though - a temporary copy of Bounds is used in the method.

Values in Brush, like the Color and Style properties, are used to draw the filled rectangle. Style determines the routine(s) called to fill the drawing area as follows:

bsSolid
Fills the specified area with the Brush color. If the rectangle covers the entire width and height for the canvas and Clipping is not enabled, the FillColor method is used. Otherwise, the FillRectangleColor method is called using the adjusted bounds for the canvas.
bsPattern
Calls FillRectanglePattern to fill the rectangle with the pattern specified for the Brush.
bsImage
Fills the rectangle with the image assigned to the Brush. Uses RelativeBrushImage to determine whether FillRectangleImageRel or FillRectangleImage is called for the operation. A PixelCanvasException exception is raised for the style if an image has not been assigned in Brush.
bsBDiagonal
Calls FillRectangleHashDiagonal to fill the rectangle using the size for the hash pattern.
bsFDiagonal
Calls FillRectangleHashBackDiagonal to fill the rectangle using the size for the hash pattern.
bsCross
Calls both FillRectangleHashHorizontal and FillRectangleHashVertical to fill the rectangle using the size for the hash pattern.
bsDiagCross
Calls booth FillRectangleHashDiagonal and FillRectangleHashBackDiagonal to fill the rectangle using the size for the hash pattern.
bsHorizontal
Calls FillRectangleHashHorizontal to fill the rectangle using the size for the hash pattern.
bsVertical
Calls FillRectangleHashVertical to fill the rectangle using the size for the hash pattern.

DoRectangleFill is an overridden method in TLazCanvas. It reimplements the method introduced in the TFPPixelCanvas ancestor (in FCL), and does not call the inherited method.

Modified in LCL version 3.0 to decrease the bottom and right edges of the rectangle by a single pixel. This fixes a difference between the rectangle fill and a border drawn in the Rectangle method. Rectangle with the bounds adjusted and used in the method. Implements a polygon fill algorithm not present in fcl-image prior to FPC version 3.2.3.

Implements a polygon fill algorithm not present in fcl-image. Part of the algorithm is explained here.

DoPolygonFill is defined when using FPC versions prior to 3.2.3. In FPC 3.2.3, the method already exists in the TFPPixelCanvas ancestor and is not needed in TLazCanvas.

Modified in LCL versions after 2.2.4 to call DrawPixel instead of SetColor when drawing pixels between points on the polygon. This allows the DrawingMode (opacity, alphablending, custom) to be applied to the pixels. Adds support for the non-zero winding rule in the fill operation. Array with the TPoint records representing the polygon vertices. Draws a line using the specified coordinates and Pen for the canvas. Initial horizontal coordinate for the line. Initial vertical coordinate for the line. Terminal horizontal coordinate for the line. Terminal vertical coordinate for the line. Performs actions needed to copy a source rectangle from the specified canvas.

DoCopyRect is an overridden method in TLazCanvas. It is used to copy values from the specified source rectangle in the Canvas argument to the location specified in X and Y. DoCopyRect reimplements the method from an ancestor class (TFPPixelCanvas).

X and Y contain the left, top coordinates on the Lazarus canvas where the copied values are stored.

Canvas is the TFPCustomCanvas instance with the values for the SourceRect argument.

SourceRect is the TRect instance width the Left, Top, Right and Bottom coordinates for the rectangular region copied from Canvas.

DoCopyRect calls the CanvasCopyRect method to perform the actions needed to perform the copy operation using the specified arguments.

Left coordinate where the copied values are stored on the Lazarus canvas. Top coordinate where the copied values are stored on the Lazarus canvas. Canvas instance that is the source for the values copied in the method. TRect instance with the Canvas coordinates copied in the method. Performs actions needed to draws the specified image at the given coordinates using AlphaBlending.

DoDraw is an overridden method in TLazCanvas. It reimplements the method from an ancestor class (TFPixelCanvas), and calls the AlphaBlend_Image method to draw the specified image at the given position.

X and Y contain the left and top coordinates on the Lazarus canvas where the image is drawn.

AImage is the TFPCustomImage instance drawn at the specified position.

DoDraw is used to implement the DoDrawImage method.

Left coordinate on the Lazarus canvas where the specified image is drawn. Top coordinate on the Lazarus canvas where the specified image is drawn. Image drawn on the Lazarus canvas at the specified position. Indicates if a valid image was provided in the constructor.

HasNoImage is a Boolean member used to indicate if a valid TFPCustomImage was provided as an argument to the Create constructor. Used in the implementation of the UpdateControlLazImageAndCanvas routine for non-native custom drawn window controls.

Native device context for the canvas.

NativeDC is a PtrInt member which contains the device context used to render a custom-drawn LCL control.

Member with extra FreeType font data from the canvas or device context. Used in custom-drawn LCL controls. Member with the TLazCanvasImageFormat instance used to speed up drawing. Member with the GDI Handle for an image. Used in custom-drawn LCL controls. Constructor for the class instance.

Create is the constructor for the class instance. Create calls the inherited constructor using AnImage as an argument.

Create allocates resources for the GraphicStateList property. Create sets the value for the HasNoImage member to True when AnImage has not been assigned (contains Nil).

Screen image for the control rendered on the canvas. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that resources allocated for GraphicStateList, AssignedBrush, and AssignedPen are freed. Destroy calls the inherited destructor prior to exiting from the method.

Sets the value in the ClipRegion property. Region stored in the property. Saves the current canvas state in the GraphicStateList member.

SaveState is an Integer function used to save the current canvas state in the GraphicStateList member. SaveState creates an instance of TLazCanvasState with copies of the current values for Brush, Pen, and Font. Values from BaseWindowOrg, WindowOrg, and Clipping are also assigned to the class instance.

The return value contains the ordinal position in GraphicStateList where the canvas state was added in the method.

Use RestoreState to restore the canvas to the state stored at a specified position in the list.

Ordinal position in GraphicStateList where the saved canvas state was stored. Restores the canvas to the state stored at the specified position. Ordinal position in GraphicStateList restored in the method. Sets the canvas to the default values/state used in the LCL TCanvas class. Alpha blends the specified content from the source canvas onto the canvas instance.

AlphaBlend combines the content in ASource with the current class instance to create the appearance of an image with partial or full transparency. The current class instance provides the background for the combined content.

ADestX and ADestY provides the left and top coordinates where the content from ASource is overlayed.

ASourceX, ASourceY, ASourceWidth and ASourceHeight contain the coordinates and dimensions for the image area retrieved from the ASource canvas.

AlphaBlend ensures that the specified source content is not too large for the destination area. The dimensions in ASourceWidth and ASourceHeight are adjusted if any part of the image is outside the destination area.

AlphaBlend creates an inverse mask for the alpha channel used on the pixels in ASource. The mask is applied to the RGB components for the Colors in the current class instance. The alpha channel in Colors is set to alphaOpaque for the combined content.

AlphaBlend is used in the implementation of the AlphaBlend_Image method.

Topics of Interest (but not documented in FCL)

  • TFPCustomCanvas.Colors (in fpcanvas.pp)
  • TFPImageCanvas (in fpimgcanv.pp)
  • TFPColor (in fpimage.pp)
 Lazarus canvas with the content alpha blended onto the current class instance. Left coordinate where the content in ASource is applied. Top coordinate where the content in ASource is applied. Left coordinate for the content in ASource applied in the method. Top coordinate for the content in ASource applied in the method. Width (in pixels) of the content in ASource applied in the method. Height (in pixels) of the content in ASource applied in the method. Performs an AlphaBlend operation assuming a white background.

This is a safer version for use where the destination pixels may not be consistent or valid. It will draw as if the target area contained opaque white pixels.

Lazarus canvas with the content alpha blended onto the current class instance. Left coordinate where the content in ASource is applied. Top coordinate where the content in ASource is applied. Left coordinate for the content in ASource applied in the method. Top coordinate for the content in ASource applied in the method. Width (in pixels) of the content in ASource applied in the method. Height (in pixels) of the content in ASource applied in the method. AlphaBlends the specified image onto the canvas. TFPCustomImage instance with the content applied in the method. Left coordinate where the content in ASource is applied to the canvas. Top coordinate where the content in ASource is applied to the canvas. Left coordinate for the content in ASource applied in the method. Top coordinate for the content in ASource applied in the method. Width (in pixels) of the content in ASource applied in the method. Height (in pixels) of the content in ASource applied in the method. Calls DoDraw for the specified image and coordinates. Left coordinate where the specified image is drawn on the Lazarus canvas. Top coordinate where the specified image is drawn on the Lazarus canvas. TFPCustomImage instance with the content rendered to the canvas. Copies the contents of a supported image format in ASource to the canvas. procedure CanvasCopyRect(ASource: TFPCustomCanvas; const ADestX, ADestY, ASourceX, ASourceY, ASourceWidth, ASourceHeight: Integer); TFPCustomCanvas instance with the content copied in the method. Left coordinate on the canvas where the content in ASource is copied. Top coordinate on the canvas where the content in ASource is copied. Left coordinate for the content in ASource copied in the method. Top coordinate for the content in ASource copied in the method. Width (in pixels) for the content in ASource copied in the method. Height (in pixels) for the content in ASource copied in the method. Fills the entire drawing area with the specified color.

Fills the entire drawing area with the specified color. AIgnoreClippingAndWindowOrg speeds up canvas drawing operations, but it is dangerous; don't use it unless you know what you are doing.

Color applied to the canvas area. True ignores the canvas clipping region and window origin, and fills all pixels for an underlying Image with the specified color. False (the default) limits the scope to the Width and Height for the canvas - not the range of pixels in the Image. Overloaded method which adds support for the non-zero winding rule.

Polygon() overloads an equally-named method inherited from TFPCustomCanvas which fills a polygon via DoPolygonFill(). By default, the even-odd rule is applied for filling. The current overload, however, adds support for filling the polygon by the non-zero winding rule.

In each case, the polygon is filled by drawing horizontal lines across the polygon starting at the left The intersection points of this line with the polygon segments are calculated and sorted from left to right.

In the even-odd rule, lines are drawn between adjacent intersection points in an alternating way.

In the non-zero winding rule the "winding number" (starting at zero for each line) is incremented/decremented depending on whether the hit polygon segment is oriented upward or downward. The following line segment is drawn only when the accumulated winding number is not zero.

The non-zero winding rule is selected when the Winding argument of the method is true. Otherwise the even-odd rule is applied.

The DrawPixel() method is called along the filling lines in order to apply the brush color to the canvas pixels in an either opaque or semi-transparent way.

Added in LCL version 3.0. Array with the TPoint instances for the vertices on the polygon. True if the non-zero winding rule is enabled for the canvas instance. Otherwise the polygon is filled by means of the "even-odd" rule in which alternating horizontal lines are drawn between pairs of polygon intersection points. Sets the Pen data for the canvas.

Utilized by LCLIntf.SelectObject and by the RestoreState method. This is needed because calling Assign for the Pen, Brush, or Font properties raises exceptions.

Pen data stored in the method. Sets the Brush data for the canvas.

Utilized by LCLIntf.SelectObject and by the RestoreState method. This is needed because calling Assign for the Pen, Brush, or Font properties raises exceptions.

Brush data stored in the method. Sets the Font data for the canvas.

AssignFontData copies property values in AFont to the Font for class instance, including:

  • FPColor
  • Name
  • Size
  • Bold
  • Italic
  • Underline
  • Strikethrough

No actions are performed in the method if AFont has not been assigned (contains Nil.

Utilized by LCLIntf.SelectObject and by the RestoreState method. This is needed because calling Assign for the Pen, Brush, or Font properties raises exceptions.

TFPCustomFont instance with the attributes assigned to the Font for the canvas. Pen assigned to the canvas.

These properties are utilized to implement LCLIntf.SelectObject to keep track of which pen/brush/font handle was assigned to this canvas. They are not utilized by TLazCanvas itself.

Brush assigned to the canvas.

These properties are used to implement LCLIntf.SelectObject to keep track of which pen/brush/font handle was assigned to this canvas. They are not utilized by TLazCanvas itself.

Font assigned to the canvas.

These properties are used to implement LCLIntf.SelectObject to keep track of which pen/brush/font handle was assigned to this canvas. They are not utilized by TLazCanvas itself.

Base window origin for the canvas.

The values in WindowOrg are relative to the coordinates in BaseWindowOrg. BaseWindowOrg coordinates are relative to the canvas for the containing Form. It is useful when implementing the non-native windowed controls.

Clipping region for the canvas. Window origin for the canvas.

Contains the absolute coordinates for the canvas with BaseWindowOrg summed up.