TBGRACustomBitmap and IBGRAScanner

From Lazarus wiki
Jump to navigationJump to search

Back to BGRABitmap.

This class and this interface are included in BGRABitmapTypes.

For methods (procedure and functions), see TBGRABitmap class.

TBGRACustomBitmap and IBGRAScanner

IBGRAScanner

IBGRAScanner = interface
Interface for a scanner. A scanner is like an image, but its content has no limit and it can be calculated on the fly. It is like a infinite readonly image.

Note: it must not implement reference counting even if it is an interface

TBGRACustomBitmap implements this interface and the content is repeated horizontally and vertically. There are also various classes in BGRAGradientScanner unit that generate gradients on the fly and in BGRATransform unit that provide geometrical transformations of images
procedure ScanMoveTo(X,Y: Integer);
Move to the position (X,Y) for the next call to ScanNextPixel
function ScanNextPixel: TBGRAPixel;
Scan the pixel at the current location and increments X
function ScanAt(X,Y: Single): TBGRAPixel;
Scan at any location using floating point coordinates
function ScanAtInteger(X,Y: integer): TBGRAPixel;
Scan at any location using integer coordinates
procedure ScanPutPixels(pdest: PBGRAPixel; count: integer; mode: TDrawMode);
Copy a row of pixels from X to X+count-1 to a specified destination pdest. mode indicates how to combine with existing data
function IsScanPutPixelsDefined: boolean;
Returns True if the function ScanPutPixels is available. Otherwise you need to call ScanNextPixel and combine pixels for example with SetPixel
TScanAtFunction = function (X,Y: Single): TBGRAPixel of object;
A type of function of a scanner that returns the content at floating point coordinates
TScanAtIntegerFunction = function (X,Y: Integer): TBGRAPixel of object;
A type of function of a scanner that returns the content at integer coordinates
TScanNextPixelFunction = function: TBGRAPixel of object;
A type of function of a scanner that returns the next pixel
TBGRACustomScanner = class(IBGRAScanner)
Base class for implementing IBGRAScanner interface

TBGRACustomBitmap

TBGRACustomBitmap = class(TFPCustomImage,IBGRAScanner)
This is the base class for TBGRABitmap. It is the direct parent of TBGRADefaultBitmap class, which is the parent of the diverse implementations. A bitmap can be used as a scanner using the interface IBGRAScanner
Caption: string;
User defined caption. It does not appear on the image
FillMode: TFillMode;
Method to use when filling polygons (winding or alternate). See BGRAGraphics
LinearAntialiasing: boolean;
Specifies if linear antialiasing must be used when drawing antialiased shapes
ResampleFilter : TResampleFilter;
Resample filter is used when resizing the bitmap
ScanInterpolationFilter: TResampleFilter;
Scan interpolation filter is used when the bitmap is used as a scanner (interface IBGRAScanner)
ScanOffset: TPoint;
Offset to apply when the image is scanned using IBGRAScanner interface
property Width: integer read;
Width of the image in pixels
property Height: integer read;
Height of the image in pixels
property ClipRect: TRect read write;
Clipping rectangle for all drawing functions
property NbPixels: integer read;
Total number of pixels. It is always true that NbPixels = Width * Height
property ScanLine[y: integer]: PBGRAPixel read;
Returns the address of the left-most pixel of any line. The parameter y ranges from 0 to Height-1
property LineOrder: TRawImageLineOrder read;
Indicates the order in which lines are stored in memory. If it is equal to riloTopToBottom, the first line is the top line. If it is equal to riloBottomToTop, the first line is the bottom line. See miscellaneous types
property Data: PBGRAPixel read;
Provides a pointer to the first pixel in memory. Depending on the LineOrder property, this can be the top-left pixel or the bottom-left pixel. There is no padding between scanlines, so the start of the next line is at the address Data + Width. See BGRABitmap tutorial 4
property RefCount: integer read;
Number of references to this image. It is increased by the function NewReference and decreased by the function FreeReference
property Empty: boolean read;
Returns True if the bitmap only contains transparent pixels or has a size of zero
property HasTransparentPixels: boolean read;
Returns True if there are transparent or semitransparent pixels, and so if the image would be stored with an alpha channel
property AverageColor: TColor read;
Average color of the image
property AveragePixel: TBGRAPixel read;
Average color (including alpha) of the image
property CanvasFP: TFPImageCanvas read;
Canvas compatible with FreePascal
property CanvasDrawModeFP: TDrawMode read write;
Draw mode to used when image is access using FreePascal functions and Colors property
property Bitmap: TBitmap read;
Bitmap in a format compatible with the current GUI. Don't forget to call InvalidateBitmap before using it if you changed something with direct pixel access (Scanline and Data)
property Canvas: TCanvas read;
Canvas provided by the GUI
property CanvasOpacity: byte read write;
Opacity to apply to changes made using GUI functions, provided CanvasAlphaCorrection is set to True
property CanvasAlphaCorrection: boolean read write;
Specifies if the alpha values must be corrected after GUI access to the bitmap
JoinStyle: TPenJoinStyle;
How to join segments. See BGRAGraphics
JoinMiterLimit: single;
Limit for the extension of the segments when joining them with pjsMiter join style, expressed in multiples of the width of the pen
property PenStyle: TPenStyle read write;
Pen style. See BGRAGraphics
property CustomPenStyle: TBGRAPenStyle read write;
Custom pen style. See geometric types
property LineCap: TPenEndCap read write;
How to draw the ends of a line
property ArrowStartSize: TPointF read write;
Size of arrows at the start of the line
property ArrowEndSize: TPointF read write;
Size of arrows at the end of the line
property ArrowStartOffset: single read write;
Offset of the arrow from the start of the line
property ArrowEndOffset: single read write;
Offset of the arrow from the end of the line
property ArrowStartRepeat: integer read write;
Number of times to repeat the starting arrow
property ArrowEndRepeat: integer read write;
Number of times to repeat the ending arrow
FontName: string;
Specifies the font to use. Unless the font renderer accept otherwise, the name is in human readable form, like 'Arial', 'Times New Roman', ...
FontStyle: TFontStyles;
Specifies the set of styles to be applied to the font. These can be fsBold, fsItalic, fsStrikeOut, fsUnderline. So the value [fsBold,fsItalic] means that the font must be bold and italic. See miscellaneous types
FontQuality : TBGRAFontQuality;
Specifies the quality of rendering. Default value is fqSystem. See miscellaneous types
FontOrientation: integer;
Specifies the rotation of the text, for functions that support text rotation. It is expressed in tenth of degrees, positive values going counter-clockwise.
FontVerticalAnchor: TFontVerticalAnchor;
Specifies how the font is vertically aligned relative to the start coordinate. See miscellaneous types
property FontHeight: integer read write;
Specifies the height of the font in pixels without taking into account additional line spacing. A negative value means that it is the full height instead (see below)
property FontFullHeight: integer read write;
Specifies the height of the font in pixels, taking into account the additional line spacing defined for the font
property FontAntialias: Boolean read write;
Simplified property to specify the quality (see FontQuality)
property FontPixelMetric: TFontPixelMetric read;
Returns measurement for the current font in pixels
property FontRenderer: TBGRACustomFontRenderer read write;
Specifies the font renderer. When working with the LCL, by default it is an instance of TLCLFontRenderer of unit BGRAText. Other renderers are provided in BGRATextFX unit and BGRAVectorize unit. Additionally, BGRAFreeType provides a renderer independent from the LCL.

Once you assign a renderer, it will automatically be freed when the bitmap is freed. The renderers may provide additional styling for the font, not accessible with the properties in this class

See font rendering

Load and save files

procedure LoadFromFile(const filename: string); virtual;
Load image from a file. filename is an ANSI string
procedure LoadFromFile(const filename:string; Handler:TFPCustomImageReader); virtual;
Load image from a file with the specified image reader. filename is an ANSI string
procedure LoadFromFileUTF8(const filenameUTF8: string); virtual;
Load image from a file. filename is an UTF8 string
procedure LoadFromFileUTF8(const filenameUTF8: string; AHandler: TFPCustomImageReader); virtual;
Load image from a file with the specified image reader. filename is an UTF8 string
procedure LoadFromStream(Str: TStream); virtual; overload;
Load image from a stream. Format is detected automatically
procedure LoadFromStream(Str: TStream; Handler: TFPCustomImageReader); virtual; overload;
Load image from a stream. The specified image reader is used
procedure SaveToFile(const filename: string); virtual; overload;
Save image to a file. The format is guessed from the file extension. filename is an ANSI string
procedure SaveToFile(const filename: string; Handler:TFPCustomImageWriter); virtual; overload;
Save image to a file with the specified image writer. filename is an ANSI string
procedure SaveToFileUTF8(const filenameUTF8: string); virtual; overload;
Save image to a file. The format is guessed from the file extension. filename is an ANSI string
procedure SaveToFileUTF8(const filenameUTF8: string; Handler:TFPCustomImageWriter); virtual; overload;
Save image to a file with the specified image writer. filename is an UTF8 string
procedure SaveToStream (Str:TStream; Handler:TFPCustomImageWriter);
Save image to a stream with the specified image writer
procedure SaveToStreamAs(Str: TStream; AFormat: TBGRAImageFormat); virtual;
Save image to a stream in the specified image format
procedure SaveToStreamAsPng(Str: TStream); virtual;
Save image to a stream in PNG format

For more methods, see derived class TBGRABitmap