Platform eXtended Library (PXL)

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

Class TBitmap

DescriptionHierarchyFieldsMethodsProperties

Unit

PXL.Bitmaps

Declaration

type TBitmap = class(TCustomCanvasImage)

Description

High-level bitmap that contains image data with multiple storage options (e.g. system, texture, etc.) and has canvas so it can be drawn into. Bitmap operations such as resizing or storage change attempts to preserve existing data as much as possible. In contrast to many other hardware-assisted components in the framework, the methods of this class return no result type but raise exceptions when issues arise.

Hierarchy

Overview

Methods

Public constructor Create(const ADevice: TCustomDevice);
Public function IsEmpty: Boolean;
Protected function CanvasBeginScene: Boolean; override;
Protected function GetRegion(const Index: Integer): TIntRectList.PItem; override;
Protected function GetTexture(const Index: Integer): TCustomBaseTexture; override;
Protected function GetTextureCount: Integer; override;
Public procedure Clear;
Public procedure CopyFrom(const Source: TBitmap);
Public procedure LoadFromFile(const FileName: StdString);
Public procedure LoadFromStream(const Stream: TStream; const Extension: StdString);
Public procedure SaveToFile(const FileName: StdString; const Quality: Pointer = nil);
Public procedure SaveToStream(const Stream: TStream; const Extension: StdString; const Quality: Pointer = nil);
Public procedure SetSize(const NewWidth, NewHeight: Integer); overload;
Public procedure SetSize(const NewSize: TPoint2i); overload; inline;
Protected procedure CanvasEndScene; override;
Protected procedure ChangeStorage(const NewStorage: TBitmapStorage); virtual;

Properties

Public property Canvas: TCustomCanvas read GetCanvas;
Public property Device: TCustomDevice read FDevice;
Public property Height: Integer read FHeight write SetHeight;
Public property PixelFormat: TPixelFormat read FPixelFormat write SetPixelFormat;
Public property Regions: TIntRectList read FRegions;
Public property Size: TPoint2i read GetSize write SetSize;
Public property Storage: TBitmapStorage read FStorage write ChangeStorage;
Public property Surface: TPixelSurface read GetCurrentSurface;
Public property Texture: TCustomBaseTexture read GetCurrentTexture;
Public property Width: Integer read FWidth write SetWidth;

Description

Methods

Public constructor Create(const ADevice: TCustomDevice);

Creates new instance of bitmap bound to the specific device.

Public function IsEmpty: Boolean;

Returns True if the bitmap has zero size (in other words, is empty) and False otherwise.

Protected function CanvasBeginScene: Boolean; override;

This function is called during TBitmap.Canvas.BeginScene call, which essentially tells bitmap's drawable texture to activate. This may trigger storage range if current storage is not drawable texture.

Protected function GetRegion(const Index: Integer): TIntRectList.PItem; override;

Returns region specified by the given index from list of existing regions and Nil if Index is outside of valid range.

Protected function GetTexture(const Index: Integer): TCustomBaseTexture; override;

Returns either lockable or drawable texture currently occupied by bitmap. Index should always be zero as bitmap can have only one texture. This may trigger storage change if current storage has no texture support.

Protected function GetTextureCount: Integer; override;

Returns number of textures as needed by canvas. In this implementation, this will always return one.

Public procedure Clear;

Clears the bitmap by filling image data with zeros.

Public procedure CopyFrom(const Source: TBitmap);

Copies the entire contents of source bitmap to current one. This ensures that current bitmap has the same size as the source. The current pixel format is not changed and if it remains unspecified before this call, it will be set to the default one. This may change bitmap storage for both source and current bitmaps depending on the currently set values to be able to reliably copy image information.

Public procedure LoadFromFile(const FileName: StdString);

Loads bitmap from external file. This may change current pixel format, size and storage type. The function uses image format manager reference provided by the associated device.

Public procedure LoadFromStream(const Stream: TStream; const Extension: StdString);

Loads bitmap from specified stream with image format identified by the given extension. This may change current pixel format, size and storage type. The function uses image format manager reference provided by the associated device.

Public procedure SaveToFile(const FileName: StdString; const Quality: Pointer = nil);

Saves bitmap to external file. This may change current storage type. The function uses image format manager reference provided by the associated device. Quality parameter is a hint that may have different interpretations depending on destination file format, platform and provider; for instance, for JPEG files, on most implementations this is just a typecast integer representing image quality between 0 and 100.

Public procedure SaveToStream(const Stream: TStream; const Extension: StdString; const Quality: Pointer = nil);

Saves bitmap to specified stream with image format identified by the given extension. This may change current storage type. The function uses image format manager reference provided by the associated device. Quality parameter is a hint that may have different interpretations depending on destination file format, platform and provider; for instance, for JPEG files, on most implementations this is just a typecast integer representing image quality between 0 and 100.

Public procedure SetSize(const NewWidth, NewHeight: Integer); overload;

Changes bitmap width and height to new parameters preserving original data as much as possible.

Public procedure SetSize(const NewSize: TPoint2i); overload; inline;

Changes bitmap size to new value preserving original data as much as possible.

Protected procedure CanvasEndScene; override;

This function is called during TBitmap.Canvas.EndScene call, which essentially tells bitmap's drawable texture to deactivate.

Protected procedure ChangeStorage(const NewStorage: TBitmapStorage); virtual;

Attempts to change current storage to a new one, preserving the data. If operation fails for some reason, the appropriate exception will be raised.

Properties

Public property Canvas: TCustomCanvas read GetCanvas;

Provides access to bitmap's canvas wrapped in TCustomCanvas, so that bitmap can be rendered into. This changes storage type to TBitmapStorage.Drawable while preserving image data.

Public property Device: TCustomDevice read FDevice;

Reference to the device class to which this bitmap is bound to.

Public property Height: Integer read FHeight write SetHeight;

Height of bitmap in pixels. Changing this preserves image contents as much as possible.

Public property PixelFormat: TPixelFormat read FPixelFormat write SetPixelFormat;

Determines the pixel format in which to store bitmap's pixels. Changing this preserves image contents as much as possible.

Public property Regions: TIntRectList read FRegions;

This list contains a list of rectangles that define sub-images (also know as "patterns" or "tiles") located on this bitmap. When drawing the current bitmap to canvas, there are methods that can take region number as parameter, therefore facilitating use of image atlases or tiles.

Public property Size: TPoint2i read GetSize write SetSize;

Size of bitmap in pixels. Changing this preserves image contents as much as possible.

Public property Storage: TBitmapStorage read FStorage write ChangeStorage;

Storage type currently occupied by bitmap. Changing this to a different value may create new type of resources, while releasing others, but the image data is preserved. Many operations may automatically change storage type depending on context, so this should be changed manually only when doing so can improve performance (for example, to start immediately with drawable texture instead of going through system/lockable stages).

Public property Surface: TPixelSurface read GetCurrentSurface;

Provides access to image data wrapped in TPixelSurface for direct pixel access. This changes storage type to TBitmapStorage.System while preserving image data.

Public property Texture: TCustomBaseTexture read GetCurrentTexture;

Provides access to image data wrapped in TCustomBaseTexture, so it can be used for rendering. If current storage type is system (which has no texture), this will change storage type to TBitmapStorage.Lockable.

Public property Width: Integer read FWidth write SetWidth;

Width of bitmap in pixels. Changing this preserves image contents as much as possible.

Copyright © 2000 - 2017 Yuriy Kotsarenko. Help files generated by PasDoc.