Graphics32

The Graphics32 Library

Features License Donate Contacts Naming Conventions SSE2 Optimizations Changes

Classes (Alphabetical)

TAdaptiveSuperSampler

TAffineTransformation

TAlbrechtKernel

TArrowBar

TBackend

TBitmap32

TBitmap32Collection

TBitmap32Item

TBitmap32List

TBitmap32Resampler

TBitmapLayer

TBitmapPolygonFiller

TBlackmanKernel

TBloatTransformation

TBooleanMap

TBoxKernel

TByteMap

TClassList

TContourRasterizer

TContracter

TConvolver

TCosineKernel

TCubicKernel

TCustomBitmap32

TCustomGaugeBar

TCustomImage32

TCustomImgView32

TCustomKernel

TCustomLayer

TCustomMap

TCustomPaintBox32

TCustomPolygonFiller

TCustomRangeBar

TCustomResampler

TCustomSampler

TDilater

TDisturbanceTransformation

TDraftResampler

TEroder

TExpander

TFishEyeTransformation

TGaugeBar

TGaussianKernel

TGDIBackend

TGDIMemoryBackend

TGDIMMFBackend

THammingKernel

THannKernel

THermiteKernel

TImage32

TImgView32

TIntegerMap

TIVScrollProperties

TKernelResampler

TKernelSampler

TLanczosKernel

TLayerCollection

TLinearKernel

TLinearResampler

TMemoryBackend

TMitchellKernel

TMMFBackend

TMorphologicalSampler

TNearestResampler

TNearestTransformer

TNestedSampler

TNotifiablePersistent

TPaintBox32

TPaintStages

TPatternSampler

TPointerMap

TPointerMapIterator

TPolygon32

TPositionedLayer

TProgressiveRasterizer

TProjectiveTransformation

TRangeBar

TRasterizer

TRectList

TRegularRasterizer

TRemapTransformation

TRenderThread

TRubberbandLayer

TSelectiveConvolver

TSinshKernel

TSplineKernel

TSuperSampler

TSwizzlingRasterizer

TSyntheticImage

TTesseralRasterizer

TThreadPersistent

TTransformation

TTransformer

TTwirlTransformation

TVectorMap

TWindowedSincKernel

TWordMap

Classes (Hierarchy)

TArrowBar

TCustomGaugeBar

TGaugeBar

TCustomRangeBar

TRangeBar

TBitmap32Collection

TBitmap32Item

TBitmap32List

TClassList

TCustomKernel

TBoxKernel

TCosineKernel

TCubicKernel

THammingKernel

THannKernel

THermiteKernel

TLinearKernel

TMitchellKernel

TSinshKernel

TSplineKernel

TWindowedSincKernel

TAlbrechtKernel

TBlackmanKernel

TGaussianKernel

TLanczosKernel

TCustomPaintBox32

TCustomImage32

TCustomImgView32

TImgView32

TImage32

TPaintBox32

TSyntheticImage

TCustomPolygonFiller

TBitmapPolygonFiller

TIVScrollProperties

TLayerCollection

TNotifiablePersistent

TCustomLayer

TPositionedLayer

TBitmapLayer

TRubberbandLayer

TCustomSampler

TCustomResampler

TBitmap32Resampler

TKernelResampler

TLinearResampler

TDraftResampler

TNearestResampler

TNestedSampler

TAdaptiveSuperSampler

TKernelSampler

TContracter

TConvolver

TSelectiveConvolver

TExpander

TMorphologicalSampler

TDilater

TEroder

TPatternSampler

TSuperSampler

TTransformer

TNearestTransformer

TThreadPersistent

TBackend

TGDIBackend

TGDIMMFBackend

TGDIMemoryBackend

TMemoryBackend

TMMFBackend

TContourRasterizer

TCustomMap

TBooleanMap

TByteMap

TCustomBitmap32

TBitmap32

TIntegerMap

TVectorMap

TWordMap

TPolygon32

TPaintStages

TPointerMap

TPointerMapIterator

TRasterizer

TProgressiveRasterizer

TRegularRasterizer

TSwizzlingRasterizer

TTesseralRasterizer

TRectList

TRenderThread

TTransformation

TAffineTransformation

TBloatTransformation

TDisturbanceTransformation

TFishEyeTransformation

TProjectiveTransformation

TRemapTransformation

TTwirlTransformation

Interfaces (Alphabetical)

IBitmapContextSupport

ICanvasSupport

ICopyFromBitmapSupport

IDeviceContextSupport

IFontSupport

IPaintSupport

ITextSupport

Interfaces (Hierarchy)

IBitmapContextSupport

ICanvasSupport

ICopyFromBitmapSupport

IDeviceContextSupport

IFontSupport

IPaintSupport

ITextSupport

Types

Arrays | TBlendReg | TFloatMatrix | TRBHandles | TStretchFilter
Color Types | TBlendRegEx | TKernelMode | TRBOptions | TVectorCombineEvent
Point Types | TCombineInfo | TLogicalOperator | TRBStyle | TVectorCombineMode
Rectangle Types | TCombineMem | TLUT8 | TRectRounding | TWrapMode
TAntialiasMode | TCombineMode | TPaintBoxOptions | TRenderMode | Vector Types
TAreaChangedEvent | TCombineReg | TPaintStage | TRepaintMode | Wrap Procedure Types
TBlendLine | TConversionType | TPixelAccessMode | TScaleMode
TBlendLineEx | TDrawMode | TPixelCombineEvent | TScrollBarVisibility
TBlendMem | TFillLineEvent | TPolyFillMode | TSize
TBlendMemEx | TFixed | TRBBackgnd | TSizeGripStyle

Routines

AlphaComponent | ColorDifference | EqualRect | IntersectRect | RasterizeTransformation
AlphaToGrayscale | ColorDiv | Erode | Invert | RedComponent
ApplyBitmask | ColorExclusion | Expand | InvertRGB | RGBtoHSL
ApplyLUT | ColorMax | FillLongword | IsRectEmpty | SetAlpha
Blend | ColorMin | FillWord | Lighten | SetBorderTransparent
BlendEx | ColorModulate | Fixed Ceil | Merge | SetGamma
BlendLine | ColorScale | Fixed Division | MergeEx | Shift Arithmetic Right
BlendLineEx | ColorSub | Fixed Floor | Mirror | SinCos
BlendTransfer | Colorswap | Fixed Multiply | MoveLongword | StretchTransfer
BlockTransfer | ColorToGrayScale | Fixed Point Math | MoveWord | Swap
BlockTransferX | Combine | Fixed Round | OffsetRect | SwapConstrain
BlueComponent | Constrain | Fixed Square | Polygon | TestClip
ChromaKey | Contract | Fixed Square Root | Polyline | TestSwap
Clamp | CopyComponents | Gray32 | PolyPolygon | Transform
Color32 | CreateBitmask | GreenComponent | PolyPolygonBounds | TransformPoints
Color32Components | Creating Points | HSLtoRGB | PolyPolyline | WinColor
Color32ToRGB | Creating Rectangles | InflateRect | PtInPolygon | WinPalette
ColorAdd | Dilate | Intensity | PtInRect | Wrap
ColorAverage | EMMS | IntensityToAlpha | Rasterize

Variables

MMX_ACTIVE

Constants

Area Information Flags | DefaultAAMode | IdentityMatrix | Paint Stage Constants
Color Constants | G32Version | Layer Options Bits

Units

GR32 | GR32_Blend | GR32_Image | GR32_OrdinalMaps | GR32_Resamplers
GR32_Backends | GR32_Containers | GR32_Layers | GR32_Polygons | GR32_Transforms
GR32_Backends_Generic | GR32_ExtImage | GR32_Lowlevel | GR32_RangeBars | GR32_VectorMaps
GR32_Backends_VCL | GR32_Filters | GR32_Math | GR32_Rasterizers

Copyright ©2000-2012 Alex Denisov and the Graphics32 Team - Graphics32 v1.9.1 - Build on 28-August-2012


Overview

Graphics32 is a set of functions, classes, components and controls designed for high-performance graphics programming.

Being highly specialized for 32-bit pixel format, it provides fast operations with pixels and graphic primitives and in most cases Graphics32 considerably outperforms standard TBitmap/TCanvas classes.

The library comes with a full source code, documentation and examples.

The following topics are covered in this overview:

  • Features;
  • License;
  • Donate;
  • Contacts;
  • Naming Convention;
  • SSE2 Optimizations;
  • Changes.

See Also

Changes, Contacts, Donate, Features, License, Naming Conventions, SSE2 Optimizations


Features

Many features in Graphics32 are similar to those in standard TImage, TBitmap and TCanvas classes, however they were rewritten to accelerate and optimize drawing on 32-bit device-independent bitmaps (DIBs). It also includes a few new options.

Some of its features include:

  • Fast per-pixel access up to 100 times faster compared to standard TCanvas/TBitmap;
  • High-performance Bitmap alpha blending (including per-pixel alpha blending);
  • Pixel, line and polygon antialiasing with sub-pixel accuracy (combined with alpha blending);
  • Arbitrary polygon transformations and custom fillings;
  • Bitmap resampling with high quality reconstruction filters (e.g. Lanczos, Cubic, Mitchell);
  • A unique state-of-the-art rasterization system;
  • Affine transformations of bitmaps: rotations, scaling, etc with sub-pixel accuracy;
  • Arbitrary projective transformations of bitmaps;
  • Arbitrary remapping transformations of bitmaps (e.g. for Warping, Morphing);
  • Flexible supersampling implementation for maximum sampling quality;
  • Flicker-free image displaying components with optimized double buffering via advanced MicroTiles based repaint optimizer;
  • Multiple customizible easy-to-use overlay layers;
  • Locking of bitmaps for safe multithreading;
  • Platform independent code;
  • Switchable surface-managing back-ends;
  • A property editor for RGB and alpha channel loading;
  • Design-time loading of image formats supported by standard TPicture;

Except for extended features, Graphics32 has some important differences from the standard components. It does not heavily rely on Windows GDI, most of the functions are reimplemented and optimized specifically for 32-bit pixel format.

See Also

Changes, Contacts, Donate, License, Naming Conventions, Repaint Optimization, Sampling and Rasterization


License

As of version 1.5.1b Graphics32 is licensed under the terms of the Mozilla Public License (MPL) 1.1. You may obtain a copy of the License at http://www.mozilla.org/MPL

Starting with version 1.9 Graphics32 is also licensed under the Lesser General Public License (LGPL) 2.1 with linking exception.

You may use the files in this distribution under the terms of either the MPL 1.1 or the LGPL 2.1 with linking exception. You can find a copy of both licenses in the plain text file License.txt which is located in the root directory of the Graphics32 distribution package.

See Also

Changes, Contacts, Donate, Features, Naming Conventions


Donate

Donation

Graphics32 is free under the terms of the Mozilla Public License (MPL) 1.1 or the Lesser General Public License (LGPL) 2.1 with linking exception. However, if you wish to express your appreciation for the time and energy spend on developing, documenting, supporting and maintaining Graphics32, the team accepts with gratitude any donation made.

Donating should just be thought of as a way of showing appreciation - it will not grant any extra support or focus on specific feature requests. In general the team strives to accommodate and respond as much as possible to user responses and requests.

Two types of donations can be made. Donations for the team in general, which mainly is used to cover general expense related to Graphics32. And donations to individuals involved in the development of Graphics32 (see the list of features, the list of contributors, the list of changes, source codes or examples to aid your evaluation of the involvement of the individuals).
If you are unsure what to choose, the developer team donation is recommended.

Michael, Andre and Mattias

Thank you for your support.

See Also

Changes, Contacts, Contributors, Examples, Features, Naming Conventions


Contacts

Graphics32 SourceForge home: http://sourceforge.net/projects/graphics32

Graphics32 new home: http://graphics32.org

Graphics32 support forum: http://graphics32.org/news/newsgroups.php?group=graphics32.support

Graphics32 support newsgroup: news://news.g32.org/g32org.public.graphics32

E-mail: team@graphics32.org

Please, use the newsgroup or forum for general support questions.

Graphics32 old home: http://g32.org

old E-mail: alex@g32.org

See Also

alex@g32, Changes, Donate, Features, License, Naming Conventions, team@graphics32


Naming Conventions

Graphics32 introduces several routines (as well as some class properties and methods) which have similar action but may have different arguments or other realization details.

They follow a simple naming convention:

Postfix | Details | Example
none | Property or method does not perform any range checking of its arguments. All the coordinates should be valid. | Line
S | 'Safe' version. Validates coordinates. If necessary, clipping is performed. | LineS
T | 'Transparent' version of the method. Uses the alpha channel of the provided color to blend the drawn primitive with the background pixels. | LineT
A | Methods with 'A' postfix provide antialiasing of the drawn primitive. | LineA
X | These functions operate with coordinates in TFixed format. They automatically provide antialiasing. | LineX
F | Methods with 'F' postfix take coordinates as floating point arguments and perform antialiasing of the drawn primitive. | LineF
TS, AS, XS, FS | Valid combinations of postfixes described above. | LineFS
P | 'Pattern' version. Usually combined with TS or FS postfixes, it allows for implementation of various effects, like gradient or dashed lines (See Line Patterns). | LineFSP
W | Wrapmode version. Checks if coordinates are outside boundaries or provided ranges, and performs wrapping according to a wrapmode |

See Also

Changes, Contacts, Donate, Features, License, Line Patterns, TWrapMode


Changes

v1.9.1 (April 2012)

  • General changes

    • Additions:

      • Added XE and XE2 support;
      • Added X64 platform support;
      • Added GR32_Backends_LCL_CustomDrawn.pas — a new backend for the LCL CustomDrawn widget set;
      • Improved FPC and Lazarus support;
      • Added SSE2 assembler routines;
      • Added X64 assembler routines;
      • Additional predifined colors, similar to new colors in XE2;
      • Restructured GR32.inc and added GR32_Compiler.inc with general compiler defines;
      • Added TGDIMemoryBackend (a memory backend that offers IPaintSupport without allocating a GDI handle).

    • Bugfixes and optimizations:

      • {$EXCESSPRECISION OFF} for better X64 floating-point performance;
      • Improved pascal and SSE2 implementation of MergeReg routine;
      • Improved FillLongWord (important when clearing large bitmaps.);
      • Fixed handling of alpha in TKernelResampler;
      • Fixed wrong alpha result in integer version of HSLtoRGB;
      • Added cache for TempPath;
      • FPS controlled movement mechanism;
      • Fixed broken Mandelbrot example;
      • Fixed bugs (#3411574, #3488570, #3510129 and others);
      • Fixed issue with font size changes and FPC compiler;
      • Fixed and improved design-time support
      • Minor tweaks, bugfixes and other optimizations.

v1.9.0 (March 2010)

  • General changes

    • Additions:

      • Platform independent code
      • Switchable back-ends and platform-agnostic TCustomBitmap32 class
      • Support for memory-mapped surfaces via MMF back-ends
      • Added IDE support up to Delphi 2010
      • Preliminary Free Pascal/Lazarus support (Win32 and OS X Carbon)
      • Kylix support officially removed as of this release.
      • Added TFunctionRegistry — a class for managing run-time bindings of functions that depend on platform-dependent parameters and CPU features.
      • Updated several units that previously performed conditional binding to use TFunctionRegistry for automatic binding.
      • Implemented Assign/AssignTo to TCustomPaintBox32
      • Added TFloat FastSqrt routine
      • Added fast native support for loading and saving of 32-bit Windows bitmaps
      • Added fast HorzLineX/VertLineX procedures for horizontal and vertical lines
      • Added floatpoint overloads of TCustomImage32.BitmapToControl and ControlToBitmap
      • License changed to a dual license with MPL and LGPL 2.1 (with linking exception)

    • Optimizations:

      • CPU feature dependent optimizations
      • Rewritten Assign/AssignTo methods of TCustomBitmap32/TBitmap32, now support assignment of alpha-transparent icons
      • Optimizations in AlphaToGrayscale (proposed by Andrea Campi)
      • Optimizations in IntensityToAlpha
      • Moved Iterator procedure from GR32 to GR32_Resamplers and merged it with LinearIterator.
      • Minor tweaks and optimizations.

    • Bugfixes:

      • Fixed bug related to TCustomImage32.ControlToBitmap and BitmapToControl conversions (now more precise)
      • Minor bugfix in AlphaToGrayscale
      • Fixed wrong enumeral type order in bitmask function template
      • Fixed bug in TTransformer (inherited constructor was not called and SetTransformation only accepted non-nil values).
      • Fixed SetSampler bug for TNestedSampler
      • Fixed initialization issue in TRenderThread (thanks to Eray Hanoglu)

v1.8.3 (5 March 2007)

  • General changes

    • Additions:

      • Added new ASM/(E)MMX optimized ApplyBitmask routine for logical (bitwise) Xor/Or/And operations using a bitmask.
      • Added new TColor32Component basetypes for specifying a component or component sets (related updates to TColor32Entry).
      • Added new CopyComponents routine for copying selected ARGB components btwn bitmaps.

    • Optimizations:

      • Optimized TBitmap32.ResetAlpha, Invert and InvertRGB.
      • Optimizations in pamTransparentEdge related routines.
      • TPatternSampler now supports nonrectangular sampling patterns.

    • Bugfixes:

      • Bugfix in MMX version of BlockAverage that caused access violations on resampling.
      • Fixes for the following bugs reported on the SourceForge tracker: 1560912, 1556318
      • Fixed misbehvior when setting TCustomImage32.BufferOversize property. Changes now directly force resizing of the buffer.
      • Fixed Kylix compilation issue introduced with new multithreading support.
      • Several minor cleanups and fixes.

v1.8.2 (5 February 2007)

  • General changes

    • Additions:

      • Added new TMultiThreadedRasterizer class for performing regular rasterization using multiple threads. By defining the symbol USE_MULTITHREADING this rasterizer becomes default on multi-core systems.
      • Added TPolarTransformation and TPathTransformation classes.
      • Added TPixelAccessMode pamTransparentEdge, useful for getting smooth edges with transformations.
      • Added new optimized low-level routines to GR32_Math.pas.

    • Bugfixes:

      • Fixes for various bugs reported on the SourceForge tracker: 1445701, 1448030, 1486180, 1456950, 1460821, 1493697, 1610287, 1610292, 1611173
      • Fixed a problem in TRenderThread that cause an AV when OnAreaChanged of the destination bitmap was unassigned.
      • Fixed overflow on calculation in LineS / LineTS with big line coordinates.
      • Fixed buffer overrun error in polygon rasterization.
      • Fix: M_ColorMax, M_ColorMin, M_ColorAverage raised critical exception on old Celeron CPU.
      • Fixed problem in TKernelResampler that caused artifacts at edges for pamSafe pixel access mode.
      • Fixed installation problems in D2005.
      • Minor tweaks and optimizations.

v1.8.1 (1 March 2006)

  • General changes

    • Additions:

      • Reintroduced property editor features for all Delphi versions after D5.
      • BDS2k6 C++ personality supported.

    • Bugfixes:

      • Fixes for various bugs reported on the SourceForge tracker: 1369894, 1398880, 1403949, 1404989, 1409711, 1412953
      • Fixed problem in method TBitmap32.DrawTo(HDC, DstRect, SrcRect).
      • Fixed a compilation problem when CHANGED_IN_PIXELS define was enabled.
      • Removed mbLeft MouseDown filter in TCustomLayer.
      • TCustomLayer.Changed obeys UpdateCount.
      • Fixed a bug in the MicroTiles repaint optimizer where the buffer wasn't completely invalidated.
      • CLX and D5 compilation issues fixed (GetPropList).

  • Detailed changes

    • GR32:

        Bugfixes:

        • Fixed problem in method TBitmap32.DrawTo(HDC, DstRect, SrcRect).
        • Fixed a compilation problem when CHANGED_IN_PIXELS define was enabled.
        • [SF 1404989] SET_TS256/LineXS with CombineMode = cmMerge -> wrong output
        • [SF 1403949] Line BUG
        • [SF 1398880] Incorrect boundary test in TBitmap32.GET_TS256
        • [SF 1369894] Bug in TBitmap.Roll method

    • GR32_Containers:

        Bugfixes:

        • GetPropList compilation issue fixed on D5.

    • GR32_Images:

        Bugfixes:

        • [SF 1412953] TImgView32 holes (repaint problems in design-time).

    • GR32_Layers:

        Bugfixes:

        • mbLeft check removed from TCustomLayer.MouseDown.
        • TCustomLayer.Changed obeys UpdateCount.

    • GR32_LowLevel:

        Bugfixes:

        • ASM version of simple Clamp added.

    • GR32_MicroTiles:

        Bugfixes:

        • Bug in TMicroTilesRepaintOptimizer.Reset method fixed where the buffer wasn't completely invalidated.
        • Enhanced debug draw
        • Additional inlining support

    • GR32_Transforms:

        Bugfixes:

        • [SF 1409711 ] TAffineTransformation.GetTransformedBounds ignores ASrcRect.
        • Various CLX compilation fixes

v1.8 (1 January 2006)

  • General changes

    • Additions:

      • Global usage of new TFloat type alias instead of Single.
      • Area update support for TBitmapLayer added.
      • TTransformation changed from TPersistent to TNotifiablePersistent so as to implement a Changed method that sets TransformValid to False automatically.
      • Incorporated the Interlocked* functions in TBitmap32.Lock and TBitmap32.Unlock according to Jouni Airaksinen's suggestions.
      • Redundant code clean up + better maintainability using central protected CopyMapTo and CopyPropertiesTo methods.
      • Added BlockTransferX routine for bitmap transfers with fixed-point coordinates (using linear interpolation).
      • CLX versions of all example projects added (no guarantee that all projects are 100% CLX-compatible).
      • Delphi 4 support officially dropped as of this release.

    • Bugfixes:

      • Bug in TLayerCollection.ViewportToLocal method fixed.
      • Misbehaviour of TCustomLayer.Visible property fixed.
      • TCustomLayer.Changed and TCustomLayer.Update methods fixed (NO_UPDATE problem)
      • TAffineTransformation.TransformFloat fixed (SF bug 1372023).
      • TBitmap32Item.AssignTo implemented to fix problem "Cannot assign a TBitmap32Item to a TBitmap32Item" (SF bug 1329566).
      • Prevent AV if user sets resampler directly (e.g. Bitmap.Resampler := TLinearResampler.Create(Bitmap);).
      • Fixed a problem in TCustomImage32 that caused performance overhead for rmDirect repaint mode.
      • TSyntheticImage was not automatically rasterized upon creation.
      • Update regions in TTesseralRaserizer were not pixel-perfect.
      • Fix for memory leaks in AssignFromBitmap sub-method due to thread <-> GDI interaction.
      • Fixed a problem in integer version of HSLtoRGB.
      • Fixed TBitmap32.GetStippleColor (the ordinary interpolation routine must be used).
      • Fixed TBitmap32.SET_T256 and TBitmap32.SET_TS256 for color merging. cmMerge is now handled as a separate case.
      • Fixed TBitmap32.FillRectT for cmMerge.
      • Fixed bug in _CombineMem routine. The alpha channel was not interpolated, which is contradictory to documentation.
      • Revised Merge routines. Merge is now based on precise lookup tables. Moreover the new version is faster than the old buggy MMX version.
      • D5 compilation fixes.

  • Detailed changes

    • GR32:

        New routines:

        • UnionRect

        New types:

        • TFloat: alias for Single

    • GR32_Blend:

        New routines:

        • CombineLine
        • ColorScale

    • GR32_Containers:

        New routines:

        • SmartAssign

    • GR32_Resamplers:

        New routines:

        • BlockTransferX

v1.8 beta (9 August 2005)

  • General changes

    • Major additions:

      • Resampler Framework / Nested Sampling
      • Rasterizer Framework
      • Buffered transformations / Warping / Remap Transformation
      • Repaint optimizations (MicroTiles Repaint optimizer)

    • Other additions:

      • New transformations (Twirl, Bloat, Disturbance, FishEye)
      • Fast transformations using TRemapTransformation
      • Kernel classes (implementing reconstruction filters) for TKernelResampler
      • Antialiasing by using regular and irregular super sampling methods
      • Spatial convolution and morphological operations
      • Vector maps, supporting .msh fileformat (useful for rasterizing/buffering transformations)
      • New ordinal map classes for Boolean-, Word- and Integer-sized data elements
      • New WrapMode property and wrapping Pixel properties
      • Scrollbar visibility control and new scale modes
      • Independent scales in TCustomImgView32 / TImgView32
      • TRubberbandLayer enhancements
      • New BlendTransfer routine for blending two bitmaps using an arbitrary blend callback routine
      • New polygonal antialiasing modes for 2x and 32x antialiasing
      • Improved performance in TPolygon32 rasterization routines
      • New draw mode, dmTransparent, for color key tranparency
      • FastMove support
      • New class registration mechanism using TClassList
      • Help documents updated with new additional topics
      • Restructured examples:

        • new examples:
        TextureBlend_Ex, NestedSampling_Ex, Resamplers_Ex, ImgWarping_Ex, Visualization_Ex

        changed examples:
        GradLines_Ex, Polygons_Ex, ImgView_Layers_Ex, Image32_Ex, Sprites_Ex

    • Bugfixes:

      • Fixed AV with Graphics32 usage in DLLs on WinXP
      • Fixed jagged lines problem in LineS, LineTS and LineAS

  • Detailed changes

    • GR32:

        New routines:

        • RGBtoHSL(RGB: TColor32; out H, S, L: Byte)
        • HSLtoRGB(H, S, L: Integer)
        • EqualRectSize

        New classes:

        • TNotifiablePersistent
        • TThreadPersistent (changed)
        • TCustomSampler
        • TCustomResampler

        Changes in TBitmap32:

          New methods:

          • BeginMeasuringMode
          • EndMeasuringMode
          • OnAreaChanged

          New properties:

          • MeasuringMode
          • StretchFilter deprecated, use TBitmap32.Resampler / TBitmap32.ResamplerClassName instead
          • WrapMode
          • PixelW / TBitmap32.PixelXW / TBitmap32.PixelFW

    • GR32_Blend:

        New routines:

        • ColorAverage

    • GR32_Containers (New Unit):

        New classes:

        • TRectList
        • TPointerMap
        • TPointerMapIterator
        • TClassList

    • GR32_Image:

        Changed types:

        • TScaleMode: new modes smOptimal and smOptimalScaled

        Changes in TCustomPaintBox32:

          New methods:

          • ForceFullInvalidate

          New properties:

          • RepaintMode

        Changes in TCustomImage32:

          New properties:

          • ScaleX
          • ScaleY

          New events:

          • OnScaleChange

        Changes in TIVScrollProperties:

          New properties:

          • Visibility (see TCustomImgView32.Scrollbars.Visibility)

    • GR32_Layers:

        Changes in TLayerCollection:

          New methods:

          • ViewportToLocal, LocalToViewport
          • GetViewportScale, GetViewportShift

          Structural changes:

          • CoordXForm deprecated, use ViewportToLocal, LocalToViewport, GetViewportScale, GetViewportShift instead
          • Owner type changed to TPersistent

        Changes in TCustomLayer:

          New methods:

          • Update
          • Update(Rect)
          • Changed(Rect)

        Changes in TPositionedLayer:

          New methods:

          • GetAdjustedRect(const R: TFloatRect): TFloatRect;

        Changes in TRubberbandLayer:

          New properties:

          • TRubberbandLayer.FrameStippleCounter

    • GR32_LowLevel:

        New routines:

        • FillLongword MMX optimized
        • MoveLongword with FastCode FastMove support via GR32.inc or project define
        • MoveWord

        Structural changes:

        • MulDiv moved to GR32_Math

    • GR32_Math (New Unit)

        New routines:

        • FixedFloor, FixedCeil
        • FixedMul, FixedDiv
        • FixedRound
        • FixedSqr, FixedSqrtLP, FixedSqrtHP
        • SinCos
        • MulDiv (moved from GR32_LowLevel)

    • GR32_MicroTiles (New Unit)

        New routines:

        • many MicroTiles auxiliary routines

        New classes:

        • TMicroTilesMap
        • TMicroTilesRepaintOptimizer

    • GR32_OrdinalMaps.pas (New Unit) / replaces GR32_ByteMaps.pas

        New classes:

        • TBooleanMap
        • TByteMap (moved from GR32_ByteMaps)
        • TWordMap
        • TIntegerMap

    • GR32_Polygons:

        Changed types:

        • TAntialiasMode: new modes am2times and am32times

        New routines:

        • PolygonBounds
        • PolyPolyBounds

        Miscellaneous changes:

        • minor optimizations to polygon rendering

    • GR32_Rasterizers (New Unit)

        New routine:

        • CombineInfo

        New classes:

        • TRasterizer
        • TRegularRasterizer
        • TSwizzlingRasterizer
        • TProgressiveRasterizer
        • TTesseralRasterizer
        • TContourRasterizer

    • GR32_RepaintOpt (New Unit)

        New classes:

        • TRepaintOptimizer

    • GR32_Resamplers (New Unit)

        New types:

        • TKernelMode

        New routines:

        • BlendTransfer
        • BlockTransfer, StretchTransfer (moved from GR32_Transforms)
        • Convolve, Dilate, Erode, Expand, Contract
        • IncBuffer, MulitplyBuffer, BufferToColor32, ShrBuffer
        • CreateJitteredPattern
        • RegisterResampler, RegisterKernel

        New classes:

        • TCustomKernel
        • TNearestKernel
        • TLinearKernel
        • TCosineKernel
        • TSplineKernel
        • TMichellKernel
        • TCubicKernel
        • THermiteKernel
        • TWindowedSinKernel
        • TLanczosKernel
        • TGaussianKernel
        • TBlackmanKernel
        • THannKernel
        • THammingKernel
        • TSinshKernel
        • TBitmap32Resampler
        • TNearestResampler
        • TLinearResampler
        • TDraftResampler
        • TKernelResampler
        • TNestedSampler
        • TTransformer
        • TNearestTransformer
        • TSuperSampler
        • TAdaptiveSuperSampler
        • TPatternSampler
        • TKernelSampler
        • TConvolver
        • TSelectiveConvolver
        • TMorphologicalSampler
        • TDilater
        • TEroder
        • TExpander
        • TContracter

    • GR32_System:

        New routines:

        • GetTickCount (for Linux)

        New classes:

        • TPerfTimer

        Miscellaneous changes:

        • EMMX/MMX2 detection added (used for MicroTiles Repaint Optimizer),
        • global performance timer named GlobalPerfTimer added

    • GR32_Transforms:

        New routines:

        • RasterizeTransformation
        • new overloaded Transform routines

        New classes:

        • TTwirlTransformation
        • TBloatTransformation
        • TDisturbanceTransformation
        • TFishEyeTransformation
        • TRemapTransformation

        Structural Changes:

        • BlockTransfer and StretchTransfer moved to GR32_Resamplers

    • GR32_VectorMaps (New Unit)

        New types:

        • TFixedVector

        New classes:

        • TVectorMap

v1.7.1 (25 February 2005)

  • Bugfixes

    • fixes for AVs in new line drawing methods (LineS, LineTS, LineAS)
    • replaced incorrect call of VertLineS and HorzLineS in LineTS and LineAS with VertLineTS and HorzLineTS
    • fix for buffer reallocation inefficiency in TCustomPaintBox32 (non-critical, long standing)
      This should improve performance on resizing for all TCustomPaintBox32 derived controls.
    • added missing call to inherited constructor in TPolygon32 constructor (caused big trouble on Win9x/WinME systems)
    • RenderText now ignores Windows-based font smoothing in VCL
      (VCL-only change because the QT version that's used in CLX doesn't support disabling font antialiasing, neither in Windows nor in Linux/X11)
    • CLX compilation fixes
    • C++ Builder compilation fixes
    • ColorMul removed (duplicate of ColorModulate)
    • minor cleanups

v1.7 (16 January 2005)

  • New Features

    • clipping rect support (all safe drawing operations are clipped to a rect)
    • support for custom polygon fillings (via callback or polygon filler objects)
    • support for polygon transformation (permanent or while drawing)
    • update to transformation classes to make them more suited for general usage
    • polygon performance enhancements
    • new CombineMode property in TBitmap32
    • TRubberbandLayer enhancements
    • additional color algebra functions
    • more versatile TBitmap32.ResetAlpha method (overloaded)
    • Delphi 2005 (Win32) support (optional inlining where applicable)
    • small speed enhancements

  • Bugfixes

    • fix for RenderText problems with letters that spread below baseline
    • fix for bug in TBitmap32.Rotate180
    • fix for problem in TBitmap32.Assign that caused transparent regions in metafiles and icons to appear in blue when they really should be white.
    • fix for problem where the buffer content on repaint in TPaintBox32 wasn't validated
    • fix for problem where C++ Builder threw linker errors (HDC methods and "hoisted overload" or E2113) in GR32.pas and GR32_Image.pas
    • fix for linear/draft bug with bitmaps of size 100x1 et al.
    • fix for bug in Transform that caused the outline of the source bitmap to appear in OuterColor
    • fix for the 3DNow detection (caused "external exception" on some machines when sfDraft was used)
    • fix for dysfunctional OnMouseEnter and OnMouseLeave in TCustomImage32
    • fix for CheckParams problem in ApplyLUT
    • fix to preserve alpha channel in ApplyLUT and ColorToGrayscale

v1.6 (21 July 2004)

  • Changes

    • Graphics32 now fully supports CLX cross-platform development;
    • Example projects have been successfully converted and tested in Linux;
    • Fixed issues in GR32_Transforms that could potentially cause access violation;
    • Added sfDraft resampling filter with MMX optimization;
    • Added sfCosine resampling filter;
    • Added PixelF/X properties that read and write pixels with antialiasing;
    • SetPixelF/X methods have been deprecated;
    • Added new MMX optimized color algebra routines to GR32_Blend (Add, Subtract, Multiply etc.);
    • Added AntiAliasMode property to TPolygon32 for dynamically changing antialias level at runtime;
    • Added support for 4x supersampling antialias of polygons (significantly faster but with less quality);
    • Unicode support for TBitmap32.Text* and TBitmap32.Rendertext methods;
    • Fixed blending bug (the "not fully opaque" issue);
    • Performance optimizations (MMX) in blending routines and Transforms;
    • Several minor additions and optimizations.

Earlier releases (v0.9 - v1.5.1b)

  • Summary

      v1.5.1b (5 July 2004)

      Changed license to MPL. Everything else is identical with v1.5.1.

      v1.5.1 (8 June 2003)

      Fixed resource leaks in TBitmap32.Canvas and TBitmap32.Font.

      A small bug fix in TRubberbandLayer.MouseMove

      Added a new resampling option which is controlled through the FullEdge variable in GR32_Transforms.pas. To see how it affects resampled image, see the new example in the FineResample_Ex directory. The default value of FullEdge is True; change FullEdge back to False to get resampling results as in previous versions.

      v1.5 (15 January 2003)

      Added packages for Delphi 7. The library should also compile with C++ Builder 6.

      v1.5 beta 2 (27 July 2002)

      Completely rewritten bitmap resampling routines: added DstClip parameter to BlockTransfer and StretchTransfer, added new resampling filters. Warning: sfLinear2 filter has been removed - use sfLinear instead.

      Added new TBitamp32 methods: FlipHorz, FlipVert, Rotate90, Rotate180, and Rotate270. Added TBitmap32.Canvas. Some changes in line drawing routines. Faster implementation of TColor <> TColor32 conversion. Other minor bug fixes.

      v1.4 (29 March 2002)

      Fixed a bug in TAffineTransformation. Exposed matrix transformation routines from GR32_Transforms for external use. Fixed handling of very small scales in TImage32. Fixed a bug in non-MMX blending. Fixed BCB packages. Added LoadFromResourceID and LoadFromResourceName wrappers. Some fixes in stippled lines with clipping (still not perfect, but now it should be more consistent). Added TBitmap32.HandleChanged.

      v1.3 (12 February 2002)

      GR32_CPUid.pas is renamed to GR32_System.pas and extended to handle windows xp visual styles. New implementation for range bars and gage bars. Fixed bugs in projective transformations, polygons, and design-time TBitmap32 editor. After a few tweaks the ImgView_Layers_Ex example should work considerable faster. Removed bgMix style from TArrowBar.Bkgnd as well as glyph properties to make range bars and gage bars compatible with visual styles in WindowsXP. Added a new property TPainBox32.Options.

      I established a new Kagi account, so if you would like to support development of Graphics32 and it successor G32, you are very welcome to make your donation here. Thank you in advance.

      v1.2 (15 January 2002)

      All the units, dfm, etc. files have been renamed from G_*.* to GR_*.*

      Renamed Rect() functions to MakeRect() to provide better BCB compatibility. Renamed TCustomMap.SetSize(Source: TPersistent) to TCustomMap.SetSizeFrom(Source: TPersistent)

      v1.01 (30 December 2001)

      Bug fixes in LineA functions, and scaling 1-pixel size bitmaps. Some steps are taken towards BCB compatibility.

      v1.0 (17 September 2001)

      A small fix in image resampling. Renamed TextOut methods to Textout (I'm not sure, but this might help in BCB compilation).

      v0.99z (13 August 2001)

      Included Borland C++ Builder installation packages. Changed references to a new web site. Fixed bugs with polygons and PaintTo method in TImage32.

      v0.99f (3 August 2001)

      Fixed (I hope) a last small glitch in font resource allocation. A few tune-ups in polygons. Added support for Delphi 6. Design-time and run-time packages have been separated (Note: deinstallation of previous version is required).

      v0.99e (31 April 2001)

      Fixed regarding OnPixelCombine event in TBitmap32. And corresponding code in StretchTransform.

      A couple of new examples added.

      v0.99d (6 February 2001)

      Changed implementation of FillRect* and FrameRect* functions, now the right/bottom line of pixels is excluded. Inverted rectangles (with negative width or height) are considered empty, they are not drawn any more. This behavior should be more consistent with GDI and with other routines in the library.

      Changed a couple of properties in TCustomRangeBar. Now Range and Increment can be of a floating point type and OnGetWindowSize event is substituted with the Window property.

      Added SizeGrip property to TCustomImgView32, as well as changed the order of the repainting a little bit, now the control scale a bit smoother.

      Fixed Win'98 resource leakage in RenderText function.

      Changed UI in the byte maps example.

      Added new example on Graphics32-based custom visual component creation.

      Most likely, this is the final beta release, next one should be v1.0.

      v0.99b

      Removed OnChanging event from all classes. Fixed a bug in TByteMap.Assign.

      A faster MulDiv implementation.

      New mouse events in TCustomImage32 were implemented to simplify mouse interaction with layers. Some internal changes in layer scaling.

      Added the OnDestroy event to layers. Added LOB_NO_UPDATE to layer option bits. Changed TRubberBandLayer to paint itself into the buffer instead of using GDI overlays, removed ResizeOptions and added the OnResizing event.

      Added Dst parameter into layer painting functions and events to support layer flattening operation (See TCustomImage32.PaintTo). Added OnInitStages event to TCustomImage32. Also I'm thinking of replacing the GDI overlays with something more useful and less flickering. It is still in the code but their usage is not recommended.

      Implemented a Sutherland-Cohen line clipping algorithm instead of slower Liang-Barsky.

      Added Flush functions to TPaintBox32 for direct copying of the back buffer to the screen.

      Updated some of the examples.

      v0.99a (25 September 2000)

      Some speed-ups in resampling functions.

      v0.99 (9 September 2000)

      New documentation is available in HTML Help format. Changed unit names. Changed implementation of TImage32 and layers (see docs). New TPaintBox32 does not support layers. TBitmapList32 is renamed to TBitmap32List and a little bit simplified. An couple of bugs fixed in TBitmap32.SetSize. One of them could lead to resource leakage. Also fixed a bug in design-time streaming. TImgView32, a new control introduced in v0.98c is improved and now it is a descendant of TImage32.

      v0.98c (19 July 2000)

      This release is to be considered as beta for v0.99. It contains most of the features planned for v0.99. I release it mostly to check the C++ Builder compatibility, and keep you up-to-date with the current development state. Note, that documentation is not completely updated. DrawLine* functions are changed to Line*. Added an ability to customize bitmap blending equation. Better and faster buffering in TPaintBox32 and its descendants. Perspective transformations are now possible as well. Introduced a new TFixed fixed point data type. A new unit, implementing controls similar to scroll bars is available together with sample control showing how to implement scroll bars with TImage32. Sample control showing how to implement rubber-banding with layers is available as well. New 'X' postfix is introduced to some line drawing routines than operate directly over fixed point arguments.

      v0.98b (3 June 2000)

      Just a few bug fixes.

      v0.98a (22 May 2000)

      A little optimization in TBitmap32.RenderText. A bug in Intensity function fixed. Some fix-ups in PolygonTS.

      v0.98 (17 May 2000)

      Delphi4 compatibility. New MMX optimization code with automatic MMX detection. A small fix in Bresenham's implementation. DrawLine* functions now have parameter controlling drawing of the last pixel. Added MoveTo*, LineTo* functions. Added text blending/antialiasing. Added polylines and polygons. DrawLineA* functions now support line opacity. Added GR32Bench.xls file with performance test results. Some other small fixes. New examples.

      v0.97a (1 May 2000)

      A bug with FillRectS, FillRectTS fixed. Added a SmartResize property to TPaintBox32, it helps to reduce the amount of back-buffer reallocations when the control resizes.

      v0.97 (29 Apr 2000)

      Complete redesign, no more MMX-specific code since the new integer version works just as fast, no more msimg32.dll dependence. New double buffering scheme, new change notification scheme, completely redesigned overlay layers implementation, new scaling and linear trannsformation implementation. Overall speed improevement.

      v0.95 (5 April 2000)

      Added MMX optimization for pixel blending. It is also used to accelerate bilinear interpolation when performing linear transformations. Well, not a huge increase in performance, but still something. Alternative non-MMX code was rearranged to increase the instruction pairing. It works a bit faster now. A few bugs with color algebra were eliminated. A couple of links regarding low-level optimization is added.

      v0.94 (31 March 2000)

      Added a new unit for byte array mapping. A little reorganization in OnChange event generation. Fixed a bug in DrawLineF/FS functions, when the last point (or part of it) was not always there it was supposed to be.

      v0.93 (23 March 2000)

      Added baTile mode to TImage32.BitmapAlign property. Added linear transformations (See documentation). EndUpdate method of TBitmap32 now does not generate change notification. The Changed method must be called explicitly. New example on linear transformation is available. A few improvements in pixel and line antialiasing.

      v0.92a (17March 2000)

      Win95/NT support bug fixed. This version emulates both bitmap transparency and bitmap alpha blending functions from msimg32.dll, however this emulation is not optimized and will be slower compared to msimg32.dll. Some other small bugs found and destroyed.

      v0.92 (16 March 2000)

      Sprite scaling is added. Removed Transparent and UseAlpha from TBitmap32 properties. A new property DrawMode is introduced instead. Windows 95 and NT compatibility compiler directive is added. TImage32 example is updated and Win95/NT version is posted. See updated documentation for details.

      v0.91 (10 March 2000)

      Some changes in TImage32 component to reduce flicker when DoubleBuffered is turned off. Fixed the multithreading example.

      v0.9 (9 March 2000)

      First public release.

See Also

Back-Ends, Contacts, Donate, Features, License, Naming Conventions, SSE2 Optimizations, TCustomBitmap32


SSE2 Optimizations

With the release 1.9.1 SSE2 optimizations have been introduced. The optimizations are entirely based on the MMX optimizations and are meant to replace the MMX code for modern systems. The MMX code is only kept for backward compatibility.

The reason to favor SSE2 optimizations over MMX optimizations is mainly due to the dual use of floating point registers. As long as all processing is done solely in fixed point or integer registers, there is no problem, but if floating point needs to be processed an expensive switch between MMX and FPU registers must be performed. This switch is performed within the function EMMS (an intrinsic to the assembler mnemonic with the same name).

Hence the fact that a call to EMMS uses only a handfull of cycles, frequent calls can slow down simple processing like blending a lot. So typically processing of small bitmaps or small areas in bitmaps will benefit mostly from optimizations in which a call to EMMS costs less or is even entirely omitted.

Unfortunately for sake of backward compatibility it was not possible to switch entirely to SSE2, as there are still many old machines without SSE2, that still benefit from the MMX optimizations. Thus, the existing infrastructure was used, but the EMMS call replaced by a stub, in case SSE2 is available. This stub is only a simple call and return, which has the least possible impact.

With this stub however - doing nothing - it is not possible to mix SSE2 optimizations with MMX optimizations (while vice versa is possible). This means that all optimizations (especially for 3rd party products using GR32 code) must be available in both MMX and SSE2 flavour. Since both technologies are very similar an update should be fairly possible.

To get rid of unused MMX optimizations entirely the symbol OMIT_MMX needs to be defined. With this define the EMMS procedure is still present, but due to its inline definition it does not have the slightest impact on performance.

NOTE: As all x86 64-bit systems feature SSE2, OMIT_MMX is defined by default here. This does not only result in a better performance, but also in smaller executables

NOTE: Due to issues with the disassembler in Delphi 7, SSE2 is disabled by default. If enabled manually the application should work fine, but debugging the application may result in a crash of the debugger.

See Also

GR32_Blend


Installation

Graphics32 supports Delphi 7, Delphi 2005 (Win32), 2006 (Delphi Win32 and C++), 2007 (Delphi Win32), 2009 (Delphi Win32), C++ Builder 6, Delphi XE and Delphi XE2.

Note 1: For Delphi 2007 and up, function inlining is automatically used to improve performance. If this is undesirable, the {$DEFINE USEINLINING} compiler define statement can be commented out in GR32.inc.

Note 2: Because some properties of range bars and gauge bars have been changed, you will encounter a few error messages when opening projects compiled with earlier versions of Graphics32. These messages can safely be ignored since the Delphi compiler will automatically remove references to missing component properties in the DFM files.

As of version 1.9, Free Pascal / Lazarus is supported for platform independent development. So far this has been tested in Win32 and in OSX 10.4, but Graphics32 is likely to run on other platforms too. Graphics32 now also uses 64 bit processors instructions in time critical code when the operating system of the target application runs 64bit processes.

Installation procedure for RAD Studio / Delphi:

  • Unzip the files;
  • Add the location of main installation directory to
    T    ools     | Environment Options | Library | Library Path for Delphi 7 and BCB 6 or
    Tools | Options | Environment Options | Delphi Options | Library - Win32 | Library Path for Delphi 2005 or higher

  • Select F ile | Open... on the menu bar. Set Files of type to Delphi package source, locate and open one of the following design-time package that fit your IDE:

    GR32_DSGN_RSXE2 for Embarcadero RAD Studio XE2 / Delphi XE2,
    GR32_DSGN_RSXE1 for Embarcadero RAD Studio XE1 / Delphi XE1,
    GR32_DSGN_RS2010 for Embarcadero RAD Studio 2010 / Delphi 2010,
    GR32_DSGN_RS2009 for CodeGear RAD Studio 2009 / Delphi 2009,
    GR32_DSGN_RS2007 for CodeGear RAD Studio 2007 / Delphi 2007,
    GR32_DSGN_RS2006 for Borland Developer Studio 2006,
    GR32_DSGN_D2005 for Delphi 2005,
    GR32_DSGN_D7 for Delphi 7,
    GR32_DSGN_CB6 for C++ Builder 6

  • A package editor window will appear. Click Compile, then click Install;
  • If compiler asks whether you want to save changes, usually it is a good idea to choose No.

Installation procedure for Lazarus:

  • Unzip the files;
  • Select P ackage | Open Package File... on the menu bar. Set Files of type to Lazarus package (*.lpk), locate and open GR32_DSGN_L.dpk
  • A package editor window will appear. Click Compile, then click Install;
  • Lazarus will ask to compile itself in order to make use of the library. Choose Yes to be able to use the library from the IDE. It will take several minutes until the IDE is compiled completely.
  • After an automatic restart you are able to use GR32 in Lazarus.


Examples

There are a few examples included with the library, which you should be able to find in the respective subdirectories VCL or CLX in the Examples subdirectory.

Here is the list of examples with short descriptions:

ByteMaps Example

Directory: General\ByteMaps_Ex (VCL only due to the 3rd party components used)

A basic demonstration of mapping a 2D array of values to TByteMap and displaying it using TPalette32.

GradLines Example

Directory: Drawing\GradLines_Ex

An example on using line patterns to draw gradient lines.

Image Warping Example

Directory: Transformation\ImgWarping_Ex

This comprehensive example demonstrates extensive use of TRemapTransformation and TVectorMap. It also implements a useful generic brush weight system, which can be applied to other aspects of image related editing (painting, uniform feathering etc.).

Image32 Example

Directory: General\Image32_Ex

This example demonstrates the properties of TImage32 that control the scale and alignment of the bitmap image.

ImgView and Layers Example

Directory: Layers\ImgView_Layers_Ex

A demonstration of using TImgView32, TPositionedLayer, TBitmapLayer and TRubberbandLayer. It also shows how it is possible to load RGB and Alpha channels from different image files into the TBitmap32 object at run-time and demonstrates an application of affine transformations. It also shows how is it possible to 'flatten' layers.

LineStippling Example

Directory: Drawing\LineStippling_Ex

An example on using line patterns to draw dashed lines.

Nested Sampling Example

Directory: Resampling\NestedSampling_Ex (VCL only due to the use of VCL exclusive TSyntheticImage)

An extensive example that features a visual editor for editing and ordering nested samplers. It demonstrates how different samplers can be combined in order to create dynamically linked sampling chains.

Additionally it shows how various rasterizers affects rendering process.

PixelF Example

Directory: Resampling\PixelF_Ex

A demonstration of interpolated PixelF property. It lets you compare the result with normal pixel access.

PixelCombine Example

Directory: Blending\PixelCombine_Ex

A short demonstration of using the OnPixelCombine method in TCustomBitmap32.

ProgressBar Example

Directory: General\ProgressBar_Ex

A simple visual component, that demonstrates how is it possible to create custom components based on TCustomPaintBox32. Note, that this component is mostly designed for demonstration purposes, do not expect too much from it.

Polygons Example

Directory: Drawing\Polygons_Ex

This example shows the application of TPolygon32 to draw thick lines and other polygons with thick outlines.

RenderText Example

Directory: Drawing\RenderText_Ex

A basic demonstration of using the TBitmap32.RenderText method.

Resamplers and Kernels Example

Directory: Resampling\Resamplers_Ex

An informative demonstration of the different resamplers and kernels available in Graphics32.

Rotate Example

Directory: General\Rotate_Ex

A simple example on using TAffineTransformation. It shows how to rotate and scale the bitmap at the same time so that it stays within the specified rectange.

RotLayer Example

Directory: Layers\RotLayer_Ex

Features custom layer class creation and demonsrtates TAffineTransformation.

Sprites Example

Directory: Layers\Sprites_Ex

A demonstration on adding, removing and animating multiple TBitmapLayer objects to TImage32.

Texture Blend Example

Directory: Blending\TextureBlend_Ex

A short demonstration of using the BlendTransfer routine and how to use custom color algebra routines.

Transform Example

Directory: Transformation\Transform_Ex

An example, which demonstrates using the Transformation routine together with TAffineTransformation and TProjectiveTransformation.

Visualization Example

Directory: Transformation\Visualization_Ex

Implements a simple set of movement (displacement transformations) renderings in line with visualizations found in various audioplayers. The formula style roughly follows conventions of Winamp Visualization Studio, and is buffered using TVectorMap. Different types of pixelrenderings (spots, particles and more) is used to visualize the movements.

See Also

Bitmap Image, BlendTransfer, Line Patterns, TCustomBitmap32.OnPixelCombine, TCustomBitmap32.Pixel, TBitmap32.RenderText, TAffineTransformation, TBitmap32, TBitmapLayer, TByteMap, TImage32, TImgView32, Color Types, TPolygon32, TPositionedLayer, TProjectiveTransformation, Transform, TRemapTransformation, TRubberbandLayer, TVectorMap


Back-Ends

1 Introduction

Traditionally bitmaps in Graphics32 have been using resources managed by the Windows GDI. While this is feasible for most usage scenarios in Windows there are some that require certain less resource-restricted approaches like handle-less bitmaps or bitmaps that rely on memory-mapped files. Prior to Graphics32 1.9 several community-driven patches existed that added these features.
With the arrival of broader platform support in Graphics32 we are separating the memory management as well as OS or graphics subsystem specific methods from the generic methods in TBitmap32 and move these portions into so called back-end classes.

2 Approach and compatibility

In order to keep backwards compatibility the TBitmap32 class still exposes the same external interface. In order to get a clean cut from the platform specific methods and properties we implemented a new in-between class TCustomBitmap32 which is truly platform agnostic and relies solely on the associated back-end class to handle its needs. As a matter of fact TCustomBitmap32 is missing all Text, Canvas and Handle methods. Back-ends may implement predefined interfaces to implement the functionality.

The back-end instance is switchable during the lifecycle of a TCustomBitmap32 instance. Conversion to the new back-end instance is handled transparently, i.e. without loosing the bitmap's surface contents. For instance this allows for temporarily switching a handle-less memory-only bitmap to a GDI bitmap with handle and vice versa. TCustomBitmap32 exposes the current back-end via its Backend property.

Code example (Switching back-ends)
begin
  MyBitmap := TBitmap32.Create;
  TMMFBackend.Create(MyBitmap); // Switch to a handle-less memory mapped file back-end...
  MyBitmap.SetSize(5000, 5000);

  // Draw onto your new big bitmap...
  // Note: No text or canvas drawing is allowed because TMMFBackend does not implement those operations.
  // Use TGDIMMFBackend instead...

  TGDIBackend.Create(MyBitmap); // Switch to a GDI back-end and convert the current buffer...
  MyBitmap.SaveToFile('test.bmp');
end;

3 Class and interface overview

Currently Graphics32 ships with the following back-end classes which are subclasses of TBackend and implement several interfaces (see below):

  • Generic back-ends
    • TMemoryBackend (default for TCustomBitmap32)
    • TMMFBackend
  • Windows GDI/VCL back-ends
    • TGDIBackend (default for TBitmap32)
    • TGDIMMFBackend
    • TGDIMemoryBackend
  • Lazarus back-ends (currently Windows, OS X Carbon, GTK)
    • TLCLBackend (default for TBitmap32)
    • TLCLMMFBackend (Windows only)

By default TBitmap32 now uses the back-end class TGDIBackend on Delphi/VCL/Windows and TLCLBackend on FreePascal/LCL/[supported OS (see above)].

Each of these back-ends may or may not implement certain pre-defined interfaces which can be queried for at runtime either directly via the back-end or indirectly via the bitmap instance:

  • IPaintSupport
  • ICopyFromBitmapSupport
  • IBitmapContextSupport
  • IDeviceContextSupport
  • ITextSupport
  • IFontSupport
  • ICanvasSupport

Please note: Most of the methods and properties left in TBitmap32 query the back-end for these specific interfaces. Failing to implement the required interfaces in the back-end class will cause the method call or property read to fail with an exception. We recommend to change your custom routines or methods to use TCustomBitmap32 instead of TBitmap32 wherever possible.

See Also

TCustomBitmap32.Backend, IBitmapContextSupport, ICanvasSupport, ICopyFromBitmapSupport, IDeviceContextSupport, IFontSupport, IPaintSupport, ITextSupport, TBackend, TBitmap32, TCustomBitmap32, TGDIBackend, TGDIMemoryBackend, TGDIMMFBackend, TMemoryBackend, TMMFBackend


Line Patterns

Graphics32 defines several functions to support non-uniform lines. This includes gradient lines, dashed lines etc.

The idea is pretty simple: TBitmap32 object holds dynamic array of colors, and a counter, which 'crawls' along the array and reads colors from its position. The line drawing algorithm queries color value from the current counter position at each point, then the counter is automatically incremented to get ready to supply the next value to line rasterisation routine.

The counter, accessed through StippleCounter property, wraps itself automatically at the edges of color array. It can move in both directions depending on stipple step, which in turn can be positive or negative. Its malue may even be fractional in this case resulting color is interpolated. The step is accessed with StippleStep property.

GetStippleColor returns color from the current counter position and automatically increments counter position by the counter step, so that next GetStippleColor call will return color value from the next position.

Drawing functions that support line patterns have 'P' in their postfix (as in LineFSP).

Warning: the counter is not thread-aware, it is shared by all threads accessing the bitmap. Additional care should be taken when multiple threads draw stippled lines in the same bitmap.

See Also

TCustomBitmap32.GetStippleColor, Examples, Examples, Naming Conventions, TCustomBitmap32.StippleCounter, TCustomBitmap32.StippleStep, TBitmap32


Repaint Optimization

1 Introduction

Two basic classes for on screen display exist in Graphics32: TCustomPaintBox32 and TCustomImage32. These classes provide the functionality all other graphical components in GR32 base on.

TCustomPaintBox32 implements a component similar to the TPaintBox component known from Borlands Visual Component Library (VCL). It differs from the latter in the way it handles the content: While TPaintBox directly draws to the display context, TCustomPaintBox32 uses an in-memory backbuffer. This technique generally called doublebuffering has its up and downsides: While it provides a convenient and simple way to avoid flickering by reducing many on-screen paint operations to just one synchronized buffer transfer (blit) from memory to screen, it does also require a significant amount of memory and bus bandwidth which in turn effectively limits the number of possible updates per second depending on the hardware used. The main problem with the implementation prior to version 1.8 of Graphics32 is that the whole buffer is transferred to screen even if just a small fraction of its area has changed, thus there is a lot of potential to improve on. One implementation that reduced this bandwidth was developed by Mattias Andersson as a patch called Clipping extension for Graphics32. The implementation in version 1.8 partly relies and extends on the techniques used in this patchset.

TCustomImage32 extends TCustomPaintBox32 by replacing the direct painting to the buffer with so called stacked Paintstages. Upon repaint these paintstages are executed in a succesive fashion from bottom to top - each stage drawing to the buffer.

Figure 1: Paintstages at runtime

Once a change happens in this stack at any given stage a deferred invalidation of the whole buffer content is triggered, which leads to a complete repaint of all stages once this invalidation request is handled by the application message queue in Windows. This is where the main problem resides: Even with the smallest change (e.g. an updating layer) the whole buffer area needs to be repainted. This approach - though simple - is naive and results in unnecessary CPU and bus and memory bandwidth utilitzation.

To sum up, we have two main problems to overcome, i.e. to optimize:

  • forced full scene repaint of paintstages to memory buffer in TCustomImage32.
  • forced full scene repaint from memory buffer to screen in TCustomPaintBox32.

2 New Structure and Repaint Optimizer

In order to achieve this, we need to restructure the repaint process in both, TCustomPaintBox32 and TCustomImage32. An external repaint optimizer should take care of the aspect of managing and optmizing changed areas. This abstraction allows better flexibility over an in-place implementation, because the repaint optimizer can be exchanged freely.

TCustomPaintBox32 implements a new property RepaintMode that allows selection of the repaint mode to be used. rmFull is equal to the old full scene repaint whereas rmOptimizer uses the repaint manager to handle only updated areas.

Figure 2: Example comparison of full scene and optimized repaint

Figure 2 shows an example comparison of the old full scene repaint (rmFull) and the new optimized repaint (rmOptimizer) for simple layer operations like moving or resizing. One can see that the new method breaks the full scene repaint down to just a fractional repaint namely those parts that were changed. Both modes are used in TCustomPaintBox32 for repaint to screen and in TCustomImage32 for repaint to buffer. Additionally there is one mode called rmDirect which is only available for TCustomPaintBox32 derived controls and does provide a direct repainting to screen. In this mode the deferred repaint technique is replaced by an immediate repaint. This technique is especially useful for the new TSyntheticImage class, which provides incremental painting of the result while still rendering.

3 Measuring Mode

Layers in Graphics32 are a special case that needs to be taken care of separately: Since layers are not forced to stay within their determined bounds (for TPositionedLayer for example), they can basically paint everywhere on the buffer. Thus we need to find some other way of determining which areas the layer is drawing to. For this to work we have extended all safe drawing operations in Graphics32 to support a method called measuring. This method can basically be thought of as a simulation mode or dry-run where nothing is actually drawn to the buffer. However, the Changed event is still triggered. So, this way the repaint optimizer can get information of which areas the operation is drawing to. As a matter of fact the repaint optimizer just needs to iterate through all marked layers (compare Figure 2), calling the Paint method of each layer with the measuring mode enabled. The information gathered in this process is used for the repaint manager's internal optimization work, ie. unifying overlapping areas and minimizing the number of rectangles to be updated.

Profiling has shown, that the measuring process adds only neglectable overhead to the repaint process. However, the developer needs to take care of certain facts in his custom code to actually take advantage of the performance benefits the repaint optimizer offers.

Code 1 Code 2
begin
  MyDrawingOperation(Buffer);
  Buffer.Changed;
end;

begin
  if not Buffer.Measuringmode then
    MyDrawingOperation(Buffer);
  Buffer.Changed(RectOfAreaThatWasChanged);
end;

Code 1 compared to Code 2 illustrates the required changes in pseudo-Pascal-code. As seen in the Code 2, a simple check for active measuring mode is introduced. In this case the actual drawing operation is omitted.

If the developer's code includes calls to the Changed method, those calls need to be changed to only represent the changed area instead of the whole buffer area. Keeping the Changed method unmodified will force a complete buffer invalidation, thus the effect of the repaint optimizer and the partial repaint therefore is reversed. Also, the custom code needs to be fully safe, meaning it has to offer full clipping support.

If the developer's custom code solely relies on the safe drawing operations provided by Graphics32, there is no need to change this code. However, doing so will likely result in better performance especially if the custom code is calling many safe drawing operations. In this case introducing the changes of Code 2 could simplify the measuring process a lot by overriding all subordinated checks by one superordinated check for measuring mode.

So, to sum up, there are two possible pitfalls in custom code that can occur with the new optimized repaint approach:

  1. Changed calls need to be taken care of (or else the whole buffer area is repainted).
  2. Custom code has to be clippable, ie. needs to obey the buffer's ClipRect property (or else visual artifacts and failures appear).

4 Internals

As already mentioned above, the repaint optimizer is responsible for managing and optimizing changed areas, which are described by rectangles. Because there can be quite a lot changes happening between repaints, the area information has to be saved in a space-saving and performance-optimal structure.

The naive approach of saving all rectangles into a list and combining them once the repaint optimizer's method PerformOptimization is called is not suitable. With each TRect instance being 16 byte in size, the memory usage is unacceptable for large sets. The overhead of reallocating such structures is also noticeable. Moreover one has to make sure not to add several overlapping rectangles to the list. Using an algorithm for this matter adds complexity to the process. Thus, we need to find a better and more flexible way of managing possibly overlapping reactangles.

Figure 3: Granularity comparison of MicroTiles and Tiles

A totally different approach is to subdivide the buffer's dimension into a matrix. Each tile of this matrix would be responsible for a 32 x 32 pixel area in the buffer. New rectangles would simply be rendered to this matrix. The memory usage stays constant because the matrix size is in fixed relation to the size of the buffer size. Also, the problem of handling overlapping reactangles is also easily solved by rendering to the matrix. Additionally unifying tiles to bigger rectangles is obviously less complex than the approach needed for determining and unifying reactangles from a list structure. However, because each tile of our matrix only holds a binary value (filled or emtpy), the granularity (compare Figure 3) of this approach is quite high and thus too much information is lost.

The method used in Graphics32 1.8 is based on the tile method but improves the granularity problem by expanding each tile in the matrix from a binary representation to an integer representation.

Figure 4: Rectangle rendered to 32 x 32 Pixel MicroTiles

So, instead of only having to restrict to full or empty as possible values, the tile contains exactly one rectangle that can further define the content. The two 16-bit values in the 32-bit integer of each tile represent the upper left and lower right corner of the inscribed rectangle relative to the upper left position of the tile (Figure 4). This allows a finer granularity and in the worst case (tile completely filled with one inscribed rectangle) the solution equals the tile based approach. However, most times the result is better, thus more information about the original shape is kept.

Because each coordinate is 8-bit wide, the tile size can scale up to 256 x 256 in size.

This method was first implemented by the developer of libart by the name MicroTile Arrays. Graphics32 implements an optimized version of its own and mixes that with some specialities: The MicroTiles Repaint Optimizer implements a simple adaptive algorithm that chooses between full scene, tile and MicroTile based operation mode depending on the current update situation.

For instance with many small rectangles (500+) the MicroTiles based optimization becomes less effective and can pose a performance overhead. In this case the adaptive algorithm will automatically downgrade to the next lower mode, which in that situation is the tiles based mode. Because the granularity is bigger in this mode, the optimization process is also less complex. Once the situation normalizes, it switches back to MicroTiles based operation mode. Thus, a good performance should be guaranteed in almost all cases.

5 Benchmarks

The Sprites_Ex project was the most important test case of all because it is exceptional in the way that it shows both, the strength and weaknesses of the MicroTiles based approach. For our tests we've extended the project slightly to be able to measure the effective frames (or updates therefore) per second.

(a)

(b)

Figure 5: Benchmark results with Sprites_Ex on PIII 1.13 GHz, WinXP, Geforce 2 mx

Figure 5 shows two results of benchmarking with different canvas resolutions. Each bitmap layer has a size of either 32 x 32 or 64 x 64 pixel picked randomly. The random seed used in the benchmark is reproducible for each test machine, thus a valid comparision is possible. As seen in the first graph (a) the MicroTiles based optimization works considerable better than the Tiles based approach. However, on our test machine it becomes less effective starting with 70 changed layers and finally the Tiles based approach outpaces it starting from 130 changed layers, because the higher granularity helps while combining the tiles to uniform rectangles. Using the MicroTiles based approach results in too many rectangles, which in this situation are less effective than fewer combined rectangles. This trend continues up to 600 rectangles. The Tiles based approach finally converges against the full scene repaint with MicroTiles being slightly worse due to the overhead involved. With so many layers the canvas area is almost completely covered with updates. For Graph (b) the results are slightly shifted due to the bigger canvas size. Both graphs show that the adaptive approach works well enough to be a feasible solution, however, the overhead of the balancing and scheduling used is noticeable in the switching regions of the graphs.

See Also

Examples, Paint Stages, TCustomPaintBox32.RepaintMode, Examples, TCustomImage32, TCustomPaintBox32, TRepaintMode, TSyntheticImage


Sampling and Rasterization

Sampling

Sampling is a very important concept within digital image processing and image analysis. Sampling is a process where color samples are acquired given their logical coordinates in the (x, y) coordinate space. Graphics32 provides a special class called TCustomSampler, that provides the necessary mechanism for implementing different sampling techniques. A sampler can be conceived as a scalar function f(x, y) that returns a color sample given a logical coordinate (x, y). A sample may be created synthetically (this is a common technique within ray-tracing, fractal rendering and pattern generation). It may also be acquired from some input hardware device. Another very common method for acquiring samples is resampling.

Resampling

Resampling is the process of reconstructing samples from a discrete input signal. The idea can also be extended from the 1D case to 2D. In the 2D case we can think of the bitmap as our signal. We have a number of pixels, aligned on a rectangular square grid. Hence we only know the actual color values at a number of discrete coordinates. In order to determine the color value of a sample at an arbitrary coordinate in a continuous image space, we need to perform interpolation for reconstructing this sample.

Descendants of TCustomResampler implement various algorithms for performing resampling and sample acquisition. A general algorithm reconstructing samples is to perform convolution in a local neighborhood of the actual sample coordinate. This method is used in TKernelResampler, where a convolution filter is specified by the TKernelSampler.Kernel property.

Graphics32 includes a class called TCustomKernel which is used as an ancestor class for various convolution kernels. For high quality resampling, one should consider using a kernel that approximates the ideal low-pass filter. The ideal low-pass filter is often referred to as a sinc filter. It can be described by the formula

Since this function has infinite extent, it is not practical for using as a convolution kernel (because of the computational overhead). TWindowedSincKernel is a base class for kernels that use the sinc function together with a window function (also known as tapering function or apodization function). This way the kernel can be constrained to a certain width and reduce the amount of computations.

For further details about resampling, see Resamplers_Ex example project.

Rasterization

By rasterizing an image, we collect samples for each pixel of an output bitmap. The rasterizer is responsible for the order in which output pixels are sampled and how the destination bitmap is updated. A rasterizer class is derived from TRasterizer, by overriding the protected DoRasterize method.

Instances of TRasterizer needs to be associated with a sampler and an output destination bitmap. Some rasterization schemes, such as swizzling, may improve cache-performance for certain applications, since samples are collected in a local neighborhood rather than row by row. Rasterizers can also provide various transition effects for creating transitions between bitmaps.

Graphics32 includes the following rasterizers:

  • TRegularRasterizer — rasterizes the bitmap row by row;
  • TProgressiveRasterizer — rasterizes in a progressive manner by successively increasing the resolution of the image;
  • TTesseralRasterizer — rasterization by sub-division;
  • TContourRasterizer — the rasterization path is determined from the intensity of the collected samples.

Nested sampling

If the input of one sampler is the output from another, then we have a nested sampler. Nested samplers are derived from the class TNestedSampler.

By nesting samplers, it is possible to create a chain of nested samplers between the sampler that generates the actual sample and the rasterizer. This mechanism is illustrated in the below image.

There are many different useful applications for nested samplers. A sampler may be associated with a transformation. This will transform the input coordinate that is passed to the sampler at the next level.

It is possible to collect more than one sample in a local neighborhood of the pixel coordinate of the output pixel. This permits the use of techniques such as super sampling, where several samples are collected in order to estimate the color of the area covered by a pixel in the destination bitmap. If super sampling is not performed, it may cause jagginess and aliasing artifacts in the output image. However, this also depends on what kind of reconstruction method is used if samples are resampled.

Another important class of nested samplers is kernel samplers. Kernel samplers compute an output sample from several subsamples in a local region of the input coordinate. Each subsample is combined with a kernel value (contained within a TIntegerMap object). A class-specific kernel operation is used to update a buffer for each collected sample. This permits a very simplistic implementation of convolution and morphological operations.

The following is a list of the different nested samplers that are included in Graphics32.

  • Transformers
    • TTransformer — transforms coordinates using an associated TTransformation object;
    • TNearestTransformer — the same as above, but for nearest neighbor resampling.
  • Super samplers
    • TSuperSampler — performs regular super sampling;
    • TAdaptiveSuperSampler — performs adaptive super sampling;
    • TPatternSampler — performs sampling according to a predefined pattern.
  • Kernel samplers
    • TConvolver — performs convolution;
    • TSelectiveConvolver — performs selective convolution;
    • TDilater — performs morphological dilation;
    • TEroder — performs morphological erosion;
    • TExpander — special expansion operation;
    • TContracter — special contraction operation.

    For further details about nested sampling, see the NestedSampling_Ex example project.

See Also

TKernelSampler.Kernel, Examples, Examples, TAdaptiveSuperSampler, TContourRasterizer, TContracter, TConvolver, TCustomKernel, TCustomResampler, TCustomSampler, TDilater, TEroder, TExpander, TIntegerMap, TKernelResampler, TNearestTransformer, TNestedSampler, TPatternSampler, TProgressiveRasterizer, TRasterizer, TRegularRasterizer, TSelectiveConvolver, TSuperSampler, TTesseralRasterizer, TTransformation, TTransformer, TWindowedSincKernel


Special Units

A series of special units are distributed with Graphics32. Among these, the units named GR32_Dsgn_XXXX.pas are used for design time purposes. See each unit description and source codes for details.


GR32_Bindings

GR32_Bindings.pas is responsible to bind procedural variables (or sometimes called 'function pointers') to specific procedures and function depending on available CPU features. The contents are not documented as this is mainly used internally. See the source code for details.


GR32_Dsgn_Bitmap

GR32_Dsgn_Bitmap.pas contains parts of the design time code used in Graphics32. The contents are not documented as this is mainly used internally. See source code for details.


GR32_Dsgn_Color

GR32_Dsgn_Color contains parts of the design time code used in Graphics32. The contents are not documented as this is mainly used internally. See source code for details.


GR32_Dsgn_Misc

GR32_Dsgn_Misc.pas contains parts of the design time code used in Graphics32. The contents are not documented as this is mainly used internally. See source code for details.


GR32_MicroTiles

GR32_MicroTiles.pas contains parts of the repaint optimizer used in Graphics32. The contents are not documented as this is mainly used internally. See the source code for details.

See Also

Repaint Optimization


GR32_Reg

GR32_Reg.pas contains the component registering code used in Graphics32. The contents are not documented as this unit is only for internal use. See the source code for details.


GR32_RepaintOpt

GR32_RepaintOpt.pas contains parts of the repaint optimizer used in Graphics32. The contents are not documented as this is mainly used internally. See the source code for details.

See Also

Repaint Optimization


GR32_System

GR32_System.pas contains code mainly used internally in Graphics32. In this unit detection of CPU features sets up appropiate function linking. If you need to detect support of specific CPU features, check the source code.


Using TImage32

Starting from v0.99 of the Graphics32 library, implementation of VCL components was changed.

This section describes behavior and properties of TCustomImage32 and TImage32 controls, as well as new realization of layers.

Since TCustomImage32 and TImage32 share the same behavior, I will denote both of them here as TImage32. Most of the discussion concerns TImgView32 as well.

Overview

TImage32 is an image displaying visual component, which also holds a collection of layers.

The image is defined as a TBitmap32 object and there exist several properties which specify how it is scaled and positioned within the control's boundaries. I will denote this image as Bitmap Image here.

The layer is, generally speaking, an entity which 'knows' how to combine itself with the back buffer of the control. TImage32 maintains a collection of layers, see 'Using Layers' for details.

When the image paints itself, it runs through several Paint Stages which determine the order in which layers and the bitmap image are painted. This order is completely customizeable.

To avoid flicker and to speed-up scaling and blending operations, each layer and the bitmap image is painted to a back-buffer of the control. See the reference of TImage32 ancestor TCustomPaintBox32 for details of the back-buffer realization.

Finally, TImage32 supports change notification (OnChange event), which is done similar to change notification in TBitmap32. Basically, it redirects change notification from its layers and the bitmap image.

See Also

Bitmap Image, Examples, TCustomImage32.OnChange, Paint Stages, TBitmap32, TCustomImage32, TCustomPaintBox32, TImage32, Using Layers


Bitmap Image

A bitmap image is represented with a TBitmap32 object and is stored in the Bitmap property. Its scale and location within the control is determined by the following properties:

BitmapAlign — specifies if the bitmap image is positioned at the top-left corner of the control (baTopLeft), centered (baCenter), tiled (baTile) or it its exact location is determined by OffsetHorz and OffsetVert properties;

ScaleMode — indicates if the bitmap image is displayed with its original size (smNormal), stretched to fit the control's boundaries (smStretch), proportionally resized to fit the control's boundaries(smResize) or proportionally scaled using its Scale property (smScale).

The bitmap image is combined with the back-buffer according to its DrawMode property. And the quality of its resampling is determined by the StretchFilter property. If its DrawMode is dmCustom, the bitmap will fire a series of OnPixelCombine events.

See Also

TCustomImage32.Bitmap, TCustomImage32.BitmapAlign, TCustomBitmap32.DrawMode, Examples, TCustomImage32.OffsetHorz, TCustomImage32.OffsetVert, TCustomImage32.OnPixelCombine, TCustomImage32.Scale, TCustomImage32.ScaleMode, TCustomBitmap32.StretchFilter, TBitmap32, TDrawMode, TStretchFilter


Paint Stages

An order in which TImage32 blends layers and bitmap image to its back-buffer is specified by paint stages.

For example, the default sequence of operations includes:

  • Clearing the visible area of the background, that is the parts of the buffered area which are not covered by the bitmap image, or the whole buffer, if the bitmap image is not in dmOpaque draw mode;
  • Drawing the dotted frame around the control boundaries (design-time only);
  • Drawing the scaled bitmap image;
  • Framing the area of the scaled bitmap image with the dotted frame (design-time only);
  • Drawing layers;

It is possible to change the order in which stages execute at run-time, add new stages, delete old ones, etc., using the PaintStages property of TImage32, which is basically a dynamic indexed list of stages.

TPaintStage Record

Each paint stage is defined with a TPaintStage record:

type TPaintStage = record
DsgnTime: Boolean;
RunTime: Boolean;
Stage: Cardinal; // a PST_* constant
Parameter: Cardinal; // an optional parameter
end;

where the Stage member holds one of the Paint Stage Constants and defines the action associated with the stage.

All stages include additional parameter, which may be ignored or may be used to store additional stage options. For example, PST_DRAW_LAYERS stage uses its parameter as a 32-bit mask to filter out invisible layers.

By default, TImage32 contains the following stages:

# | DsgnTime | RunTime | Stage | Parameter
0 | True | True | PST_CLEAR_BACKGND | not used
1 | False | True | PST_CONTROL_FRAME | not used
2 | True | True | PST_DRAW_BITMAP | not used
3 | False | True | PST_BITMAP_FRAME | not used
4 | True | True | PST_DRAW_LAYERS | $80000000

See 'Using Layers' for an explanation of the parameter value in PST_DRAW_LAYERS stage.

Customizing TImage32 at Run-Time

A PST_CUSTOM stage deserves a little bit deeper explanation. It causes the control to issue an OnPaintStage event, thus allowing to change TImage32 behavior at run-time.

The OnPaintStage event is of a TPaintStageEvent type:

type TPaintStageEvent = procedure(Sender: TObject; Dest: TBitmap32; StageNum: Cardinal) of object;

In the event handler, the application can perform some custom operations over the back-buffer of the control.

Note, that by default, TImage32 does not generate OnPaintStage. In order to make it do so, you have to insert a new stage in the PaintStages list, and set its Stage to PST_CUSTOM, or change one of the existing stages, for example:

type

TForm1 = class(TForm)

Image32: TImage32;

procedure Image32InitStages(Sender: TObject); // OnInitStages

procedure Image32PaintStage(Sender: TObject; Dest: TBitmap32; StageNum: Cardinal); // OnPaintStage

private

{ Private declarations }

public

{ Public declarations }

end;

var

Form1: TForm1;

implementation

{$R *.DFM}

procedure TForm1.Image32InitStages(Sender: TObject);

begin

// change default PST_CLEAR_BACKGND (0-th stage) to a custom handler

with Image32.PaintStages[0] do

begin

Stage := PST_CUSTOM;

Parameter := 1; // use parameter to tag the stage

end;

// insert another custom stage after the bitmap image

// was drawn, but before the control starts painting layers

with Image32.PaintStages.Insert(4) do

begin

// Note that for new stages RunTime = True by default

Stage := PST_CUSTOM;

Paramteter := 2; // use parameter to tag the stage

end;

end ;

procedure TForm1.Image32PaintStage(Sender: TObject; Dest: TBitmap32; StageNum: Cardinal);

begin

// OnPaintStage Handler

case Image32.PaintStages[StageNum].Parameter of

1: // do something with the background

2: // call another handler

end;

end;

GDI Overlays

[ Note: Most likely GDI Overlays will not be used in future versions. Do not use them ]

A final step in TImage32 repainting is the drawing of GDI overlays. This operation is performed after the bitmap image and layers have been combined in a back buffer and copied to the screen canvas.

At this stage, TImage32 fires the OnGDIOverlay event, where you can perform drawing using the standard Canvas of the TImage32.

The main reason for introducing this stage is that painting of GDI overlays does not affect the contents of the buffer, that is changes in overlay image will not cause buffer invalidation. However, GDI overlays have to be repainted each time the control repaints itself, and they are not flicker-free.

See Also

TCustomImage32.OnGDIOverlay, TCustomImage32.OnPaintStage, Paint Stage Constants, TCustomImage32.PaintStages, TPaintStage, Using Layers


Using Layers

TImage32 holds an indexed collection of layers, referenced by the Layers property. The number of layers is limited only by the amount of free memory.

Each layer is an entity, which basically 'knows' how to paint itself to the back-buffer of the control and how to interact with the mouse. Layers are indexed and their indexes are similar to the Z-order of standard controls. Layers with smaller indexes are considered to lie deeper. This common behavior is implemented in the TCustomLayer class.

Common Properties and Methods

The basic layer's behavior is controlled by its LayerOptions property, which is a 32-bit unsigned integer value composed of Layer Options Bits. This property allows for fast and relatively simple referencing of layers and groups of layers.

Consider, for example, the LOB_VISIBLE bit (31-st bit in layer options). When TImage32 repaints its layers at PST_DRAW_LAYERS stage, it uses the stage parameter from corresponding TPaintStage record as a bit-mask (default value is LOB_VISIBLE=$80000000). Being compared (logical AND operation) with LayerOptions of each layer, this mask determines whether the layer should be painted or not.

Similar situation is with reaction to mouse messages (see below).

Using LayerOptions you can easily customize the appearance and modify the order of in thich TImage32 repaints layers. For example, you may assign several categories to layers, using lower 24-bits of LayerOptions and then just change the mask in corresponding TPaintStage record to specify exactly which category you want do be displayed.

More of that, remember, that you can insert several PST_DRAW_LAYERS paint stages (even before the PST_DRAW_BITMAP stage), each with its own mask, or, alternatively, call ExecDrawLayers while handling PST_CUSTOM stages. Basically it means, that you can realize almost any complex repainting scheme, like overlay layers, underlay layers, layers, which are always on top... or always in the background, etc.

Tracking the Mouse

Each layer is capable of responding to mouse down/move/up messages, which are routed to OnMouseDown, OnMouseMove and OnMouseUp events of the container (TImage32 control). Only one layer can receive a mouse message at the time.

Searching for the layer that receives a mouse message starts from the top-most layer and ends when the first layer satisfying both of the following conditions is found:

  • Layer has LOB_MOUSE_EVENTS bit activated in its LayerOptions;
  • Layer passes a hit test (see below);

There is also a possibility to disable passing of all mouse messages to layers. Just set the MouseEvents property of the layer collection to False, and TImage32 will generate mouse events right away, without checking for possible receiving layer.

As stated earlier, layer should pass a hit test in order to receive mouse message. The hit test is, basically a boolean responce to a couple of coordinates, accomplished by the HitTest method:

function HitTest(X, Y: Integer): Boolean; virtual;

X and Y parameters here are the coordinates of the point specified relative to the top-left corner of TImage32 (in pixels). The function returns a value that indicates that the layer is 'there'. This function is overriden in descendants, for example, in TBitmapLayer, this hit test may take into consideration values stored in the alpha channel of the contained bitmap. You can also write a handler for OnHitTest event to customize hit tests at run-time.

Similar to standard controls, layers may also capture mouse messages. By default, all mouse messages are captured automatically once the mouse is pressed on top of the layer and until the mouse is released. The layer that has captured the mouse is pointed by the MouseListener property of the layer collection. (There is a few things to work on here... will do it later).

Painting Layers

Layers are painted in bottom-to-top order, starting from lower indexes. By default, only visible layers are painted, that is the ones with LOB_VISIBLE bit set, but as it was shown above, this order may be changed.

Positioned Layers

Positioned layers are the layers, you will probably use most of the time. The base class for positioned layers is TPositionedLayer. In addition to basic layer behavior, it introduces Location property (of the TFloatRect type), which specifies layer's position and size. Having location specified as a floating point rectangle helps to avoid rounding errors when layers are resized.

The location can be specified in pixels, relative to TImage32 top-left corner, or in scaled pixels, relative to the top-left corner of the bitmap image. In the second case, the scale of the layer coincides with the scale of the bitmap image and the actual location of the layer relative to the top-left corner of TImage32 may be obtained with its GetAdjustedLocation method.

See Also

Bitmap Image, TCustomImage32.ExecDrawLayers, TPositionedLayer.GetAdjustedLocation, TCustomLayer.HitTest, Examples, Layer Options Bits, TCustomLayer.LayerOptions, TCustomImage32.Layers, TPositionedLayer.Location, TLayerCollection.MouseEvents, TLayerCollection.MouseListener, TCustomLayer.OnHitTest, TCustomImage32.OnMouseDown, TCustomImage32.OnMouseMove, TCustomImage32.OnMouseUp, TBitmapLayer, TCustomLayer, Rectangle Types, Paint Stages, TPositionedLayer, TRubberbandLayer


Contributors

(in alphabetical order):

v1.8.x

Mattias Andersson <mattias@centaurix.com>:

GR32.pas:
- Added fast integer versions of HSLtoRGB and RGBtoHSL
- Added TCustomSampler and TCustomResampler
- Added dmTransparent draw mode
- Added TBitmap32.WrapMode property
- Added TBitmap32.PixelW property

GR32_LowLevel.pas:
- Added clamp, wrap and mirror routines

GR32_OrdinalMaps.pas:
- Initial developer
- Added TBooleanMap, TWordMap and TIntegerMap

GR32_Resamplers.pas:
- Initial developer
- Added TCustomKernel and descendant classes
- Added TBitmap32Resampler and descendant classes
- Added TNestedSampler
- Added TTransformer
- Added TSuperSampler, TAdaptiveSuperSampler and TPatternSampler
- Added TKernelSampler and descendant classes
- Added auxiliary routines for convolution and morphological operations
- Optimized TKernelResampler.GetSample (with Michael)
- Added BlendTransfer routine
- Added CreateJitteredPattern routine

GR32_Rasterizers.pas:
- Initial developer
- Added TRasterizer and descendant classes

GR32_Transforms.pas:
- Updated Transform procedure

GR32_ExtImage.pas:
- Initial developer
- Added TSyntheticImage and TRenderThread
- Added Rasterize auxiliary routine

GR32_Containers.pas:
- Added TClassList

Examples:
- Mandelbrot Example
- Nested Sampling Example
- Resampler Example

Andre Beckedorf <andre@metaexception.de>:

GR32.pas:
- Added MeasuringMode and changed area notification required for repaint optimizer (BeginMeasuringMode, EndMeasuringMode, OnAreaChanged)
- Added switchable back-end framework

GR32_Containers.pas:
- Added TPointerMap and TPointerMapIterator
- Added TRectList

GR32_Image.pas:
- Added support for repaint optimization to display components (TCustomPaintBox32, TCustomImage32, TCustomImgView32)
- Added property to control scrollbar visibility (TCustomImgView32.Scrollbars.Visibility)
- Added independent X and Y scale properties in TCustomImage32 along with new OnScaleChange event
- Added additional scale modes smOptimal and smOptimalScaled
- Added RepaintMode property to control whether to use repaint optimizer, direct or full scene repaint

GR32_Layers.pas:
- Replaced CoordXForm property with more flexible GetViewportShift and GetViewportScale methods in TLayerCollection (e.g. for nested layers)
- Added support for repaint optimization to TCustomLayer descendants
- Added new Update methods to TCustomLayer
- Added Options property, proportional resize and OnConstrain event

GR32_LowLevel.pas:
- Initial support for FastCode routines

GR32_MicroTiles.pas:
 - MicroTiles and Tiles auxiliary routines
- MicroTiles Repaint optimizer
- Adaptive balancing
- MMX optimization for MicroTileUnion

GR32_Polygon.pas:
- Added additional 2x and 32x supersampling mode
- Performance optimization

GR32_RepaintOpt.pas:
- Abstract Repaint optimizer class

GR32_System.pas:
- Added support for EMMX detection (used in repaint optimizer)
- Added TPerfTimer class along with global performance timer
- Added GetTickCount derivative for Linux
- Fixed AV when using Graphics32 in DLLs on WinXP

Examples:
- Modified Sprites_Ex, ImgView32_Ex, GradLines_Ex, Polygons_Ex and Image32_Ex Example

Michael Hansen <dyster_tid@hotmail.com>:

GR32.pas:
- Fixed Math related additions
- Auxiliary rectangle routines
- Misc. array types
- Added TColor32Component, TColor32Components and related routines (TColorEntry updated)
- Optimized TBitmap32.ResetAlpha

GR32_Layers.pas:
- Enhancements to TRubberbandLayer

GR32_Lowlevel.pas:
- MMX optimized FillLongword

GR32_Filters.pas:
- ASM/MMX/EMMX optimized Invert
- Added fast CopyComponents routine for copying selected ARGB components btwn. bitmaps
- Added ASM/MMX/EMMX ApplyBitmask routine for bitwise Xor/Or/And operations using a bitmask

GR32_OrdinalMaps.pas (new unit):
- Minor tweaks for TByteMap

GR32_Resamplers.pas (new unit):
- Added kmTableLinear and kmTableNearest kernel modes
- Optimized TLinearResampler
- Fixed TDraftResampler
- GetSampleFloat optimizations
- New overloaded BlendTransfer routine, supporting TBlendRegEx and MasterAlpha
- New PixelAccessMode pamTransparentEdge as a dynamic and fast alternative to SetBorderTransparent
- Minor tweaks in TPatternSampler
- Minor optimizations in pamTransparentEdge related routines

GR32_Transforms.pas:
- Added following transformation types:

- TTwirlTransformation
- TBloatTransformation
- TDisturbanceTransformation
- TFishEyeTransformation
- TRemapTransformation

- Additional performance tuning

GR32_VectorMaps.pas (new unit):
- Initial developer
- Added TVectorMap, supporting loading and saving in Photoshop .msh format

Examples:
- Image Warping Example
- Visualization Example
- Resample Example
- Texture blend Example
- Additional updates to various examples (see sources)

v1.7 and v1.6

Mattias Andersson <mattias@centaurix.com>:

GR32.pas:
- Tweaks
- PixelF/X property
- Some minor CLX/Kylix tweaks
- Added CombineMode

GR32_Image.pas:
- Ported to CLX/Kylix

GR32_Polygons.pas:
- Added TPolygon32.ContainsPoint method

GR32_Transforms.pas:
- Added sfCosine resampling filter

GR32_Blend.pas
- Pascal and MMX version of Merge algorithm
- Added MMX versions of almost all PixelCombine functions

Andre Beckedorf <andre@metaexception.de>:

GR32.pas:
- Added Unicode text methods
- Ported to CLX/Kylix
- Added CombineMode
- Added clipping rect support
- pixel-perfect line drawing methods (LineS, LineTS, LineAS)

GR32_Image.pas:
- Some part of the CLX/Kylix related changes in this unit
- Added new overrideable Mouse* methods with Layer information
- Added OverSize property in TCustomImgView32

GR32_Layers.pas:
- enhancements to TRubberbandLayer

GR32_Polygon.pas:
- Added option for dynamic antialias level adjustment at runtime along with 4x supersampling mode
- Added support for custom polygon fillings (TCustomPolygonFiller, TBitmapPolygonFiller) and transformations
- Added support for clipping to rect
- Added PolylineXSP and PolyPolylineXSP
- Additional performance tuning

GR32_RangeBars.pas:
- Ported to CLX/Kylix

GR32_System.pas:
- Added support for SSE, SSE2, 3DNow and 3DNow Ext detection

GR32_Transforms.pas:
- Update to transformation classes to make them suited for general usage

Michael Hansen <dyster_tid@hotmail.com>:

GR32.pas:
- PixelF/X property
- MMX optimized GetPixelF/X FS/XS functions

GR32_Blend.pas:
- Added Difference and Exclusion PixelCombine functions (Pascal)
- Added PixelCombine function setup, to support non MMX cpus
- Worked out bugfix for "not fully opaque" problem in some blendroutines

GR32_Transforms.pas:
- Added sfDraft resampling routines
- MMX optimized sfLinear and sfDraft
- Updated Transform to use PixelX and PixelXS

Contributors:

Arioch /BDV/:

GR32.pas
- Added WinPalette function. (merged by Mattias with some modifications)

Thomas Bauer:

GR32.pas:
- Some bugfixes (merged by Andre)

GR32_Transforms.pas:
- FullEdge related bugfixes (merged by Andre)

Soumitra Bhattacharjee:

GR32_Polygons.pas:
- Added PtInPolygon function. (merged by Mattias with some modifications)

Greg Chapman:

GR32_Filters.pas:
- Report and bugfix for the CheckParams problem in ApplyLUT. (merged by Andre)

Cleber:

GR32.pas:
- Added Color32ToRGB(A). (merged by Andre)

Dieter Köhler:

GR32_Layers.pas:
- TLayerCollection.LocalToViewport
- TLayerCollection.ViewportToLocal
- TPositionedLayer.GetAdjustedRect (all merged by Andre)

Marc Lafon:

GR32_Image.pas:
- Custom color properties for the bars (merged by Andre)

Peter Larson:

GR32_Polygons.pas:
- Initial work on polygon transformation and bitmap pattern filling.
- Some optimizations in polygon setup.

GR32_Transforms.pas:
- TransformPoints routine.

Gerd Platl :

Documentation:
- Illustration for TPolyFillMode

Andrew P. Rybin:

GR32_Image.pas:
- MouseEnter/MouseLeave (merged by Andre with some changes to match structure)

J. Tulach:

GR32.pas:
- Additional handling of chroma transperancy in TBitmap32.Assign (merged by Andre with some modifications and comments).

GR32_Transforms.pas:
- C++ Builder workaround (merged by Andre)

Bob Voigt:

GR32_Blend.pas:
- ColorMul and ColorDiv (merged by Andre)

Jens Weiermann:

GR32_Filters.pas:
- enhancements to ApplyLUT and ColorToGrayscale that preserve alpha channel (merged by Andre)

Norbert Witternigg:

- updated the example project files to Borland C++ Builder 6.

See Also

Back-Ends, Repaint Optimization


GR32

GR32.pas contains common functions and classes for working with 32-bit device independent bitmaps (DIBs). It also defines some other basic types and operations.

Contents

Types | Classes | Routines | Constants
Arrays | TBackend | AlphaComponent | Area Information Flags
Color Types | TBitmap32 | BlueComponent | Color Constants
Point Types | TCustomBitmap32 | Color32 | G32Version
Rectangle Types | TCustomMap | Color32Components |
TAreaChangedEvent | TCustomResampler | Color32ToRGB |
TCombineMode | TCustomSampler | Creating Points |
TDrawMode | TNotifiablePersistent | Creating Rectangles |
TFixed | TThreadPersistent | EqualRect |
TPixelCombineEvent |  | Fixed Point Math |
TRectRounding |  | Gray32 |
TSize |  | GreenComponent |
TStretchFilter |  | HSLtoRGB |
TWrapMode |  | InflateRect |
 |  | Intensity |
 |  | IntersectRect |
 |  | IsRectEmpty |
 |  | OffsetRect |
 |  | PtInRect |
 |  | RedComponent |
 |  | RGBtoHSL |
 |  | SetAlpha |
 |  | SetGamma |
 |  | WinColor |
 |  | WinPalette |


Arrays

Dynamic Array Types

TArrayOfByte

type TArrayOfByte = array of Byte;

type PArrayOfByte = ^TArrayOfByte;

A dynamic array of bytes.

TArrayOfWord

type TArrayOfInteger = array of Word;

A dynamic array of words.

TArrayOfInteger

type TArrayOfInteger = array of Integer;

A dynamic array of integers.

TArrayOfSingle

type TArrayOfSingle = array of Single;

A dynamic array of single-precision floating-point values.

TArrayOfArrayOfInteger

type TArrayOfArrayOfInteger = array of TArrayOfInteger;

A dynamic array of dynamic arrays of integers.

Array Reference Types

Most likely you will never use the reference types directly, however the pointer is the one of some importance. It provides indexed access to values stored in memory, and is used as the result type of the ordinal maps bits properties.

TByteArray

type TByteArray = array [0..0] of Byte;

type PByteArray = ^TByteArray;

A reference to array of byte-typed values.

TWordArray

type TWordArray = array [0..0] of Word;

type PWordArray = ^TWordArray;

A reference to array of word-typed values.

TIntegerArray

type TIntegerArray = array [0..0] of Integer;

type PIntegerArray = ^TIntegerArray;

A reference to array of integer-typed values.

See Also

TByteMap, TIntegerMap, TWordMap


Color Types

TColor32

type TColor32 = type Longword;

type PColor32 = ^TColor32;

A simple ARGB color quad, compatible with 32-bit DIBs.

TColor32 holds color information in ARGB format:

Bits 32...24 | Bits 23...16 | Bits 15...8 | Bits 7...0
Alpha | Red | Green | Blue

This order is different from ABGR pixel format used by most Windows API functions and implemented in Delphi as TColor type. A couple of functions are provided to convert colors between different standards: Color32, WinColor.

The alpha component is responsible for pixel’s opacity: zero value corresponds to complete transparency, and the value of 255 corresponds to completely opaque pixels.

Graphics32 specifies several pre-defined Color Constants, which are similar to standard ones except that they have properly filled alpha value and swapped red and blue components.

TColor32Entry

TColor32Entry = packed record
case Integer of
0: (A: Byte;
B: Byte;
G: Byte;
R: Byte);
1: (ARGB: TColor32;);
2: (Planes: array [0..3] of Byte);
3: (Components: array [TColor32Component] of Byte);
end;

type PColor32Entry = ^TColor32Entry;

A useful type for gaining fast direct read/write access to the components of TColor32 by typecasting. The following code segment shows how this typecasting can be used in different manners - we recommend using these approaches instead of auxiliary functions like RedComponent etc.:

var

AColor32: TColor32;

I: Integer;

begin

// Sets values to individual components

TColor32Entry(AColor32).A := 255;

TColor32Entry(AColor32).R := 127;

TColor32Entry(AColor32).G := 63;

TColor32Entry(AColor32).B := 31;

//Sets all planes or components ("channels") to a different random value

with TColor32Entry(AColor32) do

for I := Low(Planes) to High(Planes) do

Planes[I] := Random(255);

//Write value of Alpha component to Red, Green and Blue components

with TColor32Entry(AColor32) do

begin

Components[ccRed] := Components[ccAlpha];

Components[ccGreen] := Components[ccAlpha];

Components[ccBlue] := Components[ccAlpha];

end;

end;

TColor32Component

type TColor32Component = (ccBlue, ccGreen, ccRed, ccAlpha);

An enumerated type that specifies a given TColor32 component or plane.

TColor32Components

type TColor32Components = set of TColor32Component;

A set of TColor32Component which can be used to specify zero or more components. The order of defined components has no importance. To construct a set of components from booleans indicating component presence, use function Color32Components. If an empty set is passed to a routine that uses this type, this will (and should) in most cases lead to no processing.

TColor32Array

type TColor32Array = array [0..0] of TColor32;

type PColor32Array = ^TColor32Array;

A reference to array of TColor32-typed values.

Most likely you will never use the TColor32Array type itself, however PColor32Array is the one of some importance. It provides indexed access to color values stored in memory. For example, in TBitmap32, it is used to access pixel data.

TArrayOfColor32

type TArrayOfColor32 = array of TColor32;

A dynamic array of TColor32-typed values.

You may use the standard SetLength function for array allocation and dynamic size changes.

Do not confuse PColor32Array and TArrayOfColor32 types. While the first one holds the pointer to a memory location, the second one is a fully functional dynamic array.

TPalette32

type TPalette32 = array [Byte] of TColor32;

type PPalette32 = ^TPalette32;

A fixed-size array of 256 TColor32-typed values.

TPalette32 type is mostly used to simulate palette-based operations.

See Also

Color Constants, Color32, Color32Components, RedComponent, TBitmap32, WinColor


Point Types

Graphics32 uses coordinate system with an origin at the top-left corner. Due to performance considerations, other coordinate systems are not supported and not planned in future versions.

Point coordinates are defined with following structures:

TPoint

type TPoint = Windows.TPoint;

type PPoint = ^TPoint;

A point with integer coordinates. TPoint type, is redeclared from Windows.pas unit. It is compatible with all Delphi/Windows API calls.

TFloatPoint

type TFloatPoint = record
X, Y: Single;
end;

type PFloatPoint = ^TFloatPoint;

Defines a point with single-precision floating-point coordinates.

TFixedPoint

type TFixedPoint = record
X, Y: TFixed;
end;

type PFixedPoint = ^TFixedPoint;

TFixedPoint is bitwise-compatible with TPointFx type from Windows.pas, which is used by some API calls. TFixedPoint is not assignment-compatible with TPointFX, however, appropriate data in memory may be safely referenced by both types and it is still possible to assign between these types using, for example, Move procedure from System.pas.

TArrayOfPoint

type TArrayOfPoint = array of TPoint;

A dynamic array of TPoint.

TArrayOfFloatPoint

type TArrayOfFloatPoint = array of TFloatPoint;

A dynamic array of TFloatPoint.

TArrayOfFixedPoint

type TArrayOfFixedPoint = array of TFixedPoint;

A dynamic array of TFixedPoint.

TArrayOfArrayOfPoint

type TArrayOfArrayOfPoint = array of TArrayOfPoint;

TArrayOfArrayOfFloatPoint

type TArrayOfArrayOfFloatPoint = array of TArrayOfFloatPoint;

TArrayOfArrayOfFixedPoint

type TArrayOfArrayOfFixedPoint = array of TArrayOfFixedPoint;

Maybe last three types look a little cumbersome, but they are what it says: dynamic arrays of dynamic arrays of points. These are the types used in PolyPolyline and PolyPolygon functions to define shapes constructed of several outlines.

See Also

Creating Points, PolyPolygon, PolyPolyline, TFixed


Rectangle Types

Several data types are designated to handle rectangles:

TRect

type TRect = Windows.TRect;

TRect is redeclared from Windows.h and is compatible with Delphi/Windows API calls.

TFloatRect

type TFloatRect = record
case Integer of
0: (Left, Top, Right, Bottom: Single);
1: (TopLeft, BottomRight: TFloatPoint);
end;

A rectangle with floating-point coordinates.

TFixedRect

type TFixedRect = record
case Integer of
0: (Left, Top, Right, Bottom: TFixed);
1: (TopLeft, BottomRight: TFixedPoint);
end;

A rectangle with fixed-point coordinates.

See Also

Creating Rectangles, TFixed, Point Types, Point Types


TAreaChangedEvent

type TAreaChangedEvent = procedure(Sender: TObject; const Area: TRect; const Info: Cardinal) of object;

Desctiption

TAreaChangedEvent is the type of the OnAreaChanged event in TBitmap32. It indicates which area has changed (Area). A simple information (Info) about the area can be set.

Info is normally AREAINFO_RECT, but other flags can be set to indicate what shape the area actually has. This is especially useful for the repaint optimizer. Lines for example are specially treated with the AREAINFO_LINE + LineWidth encoded into the Info parameter.

See Also

Area Information Flags, TCustomBitmap32.DrawMode, TCustomBitmap32.OnAreaChanged, Rectangle Types


TCombineMode

type TCombineMode = (cmBlend, cmMerge);

Description

TCombineMode defines how drawing operations combine the foreground color with the background.
It also determines how a bitmap is combined with the background when DrawMode is set to dmBlend.

  • cmBlend - Fast blending of foreground color with the background color using the supplied alpha. This method is not suited for working and preserving alpha-channels. Use this more if you want to blend directly to the display buffer.
  • cmMerge - Uses a completely different formula that also merges the alpha-channels. This mode is slower than blending but is suited for working with alpha-channels (eg. when composing in temporary buffers).

See Also

TCustomBitmap32.DrawMode


TDrawMode

type TDrawMode = (dmOpaque, dmBlend, dmCustom, dmTransparent);

Description

TDrawMode defines how the bitmap is combined with the background. This is the type for DrawMode property of TBitmap32 class, and it is also passed as parameter in BlockTransfer and StretchTransfer functions.

  • dmOpaque – a color information from the foreground image completely replaces the background data;
  • dmBlend – foreground and background colors are blended together using per-pixel opacity of the foreground bitmap (stored in its alpha channel), multiplied by its MasterAlpha;
  • dmCustom – colors are mixed using OnPixelCombine event, that is essentially a call-back function allowing for any custom blending routine.
  • dmTransparent – color key transparency: any pixel that matches TBitmap32.OuterColor is treated as transparent.

See Also

BlockTransfer, TCustomBitmap32.DrawMode, TCustomBitmap32.MasterAlpha, TCustomBitmap32.OnPixelCombine, TCustomBitmap32.OuterColor, StretchTransfer, TBitmap32


TFixed

type TFixed = type Integer;

type PFixed = ^TFixed;

Description

In order to accelerate some calculations, Graphics32 extensively uses fixed point arithmetics, which is mostly based on TFixed type:

TFixed is a 32-bit fixed point value in 16.16 format, that is 16 bits represent signed integer part and 16 bits represent unsigned fractional part. This format is bitwise-compatible with TFixed type from the Windows.pas unit, except it does not use a record to store the value, which allows for faster function parameter passing and faster value copying and assignment.

Conversion from floating to fixed point is very simple:

Fixed := Round(Single * 65536);

See Also

Fixed Point Math


TPixelCombineEvent

type TPixelCombineEvent = procedure(F: TColor32; var B: TColor32; M: TColor32) of object;

Desctiption

TPixelCombineEvent is a type for OnPixelCombine callback function. It specifies a function which takes foreground color (F) and blends it with the background (B). This function may optionally use master alpha value (M). Moreover, in dmCustom mode master alpha value does not necesserely have to be in [0…255] range anymore, you are free to use all its 32-bits.

See Also

TCustomBitmap32.DrawMode, TCustomBitmap32.OnPixelCombine, Color Types


TRectRounding

type TRectRounding = (rrClosest, rrOutside, rrInside);

Desctiption

TRectRounding type is involved in conversion from TFloatRect/TFixedRect to TRect. It specifies how the coordinates are rounded:

  • rrClosest – a simple Round() function is used for each coordinate;
  • rrOutside – Floor() is used for Left and Top; Ceil() – for Right and Bottom;
  • rrInside – Ceil() is used for Left and Top; Floor() – for Right and Bottom;

See Also

Creating Rectangles, Rectangle Types, Rectangle Types, Rectangle Types


TSize

type TSize = record
Cx, Cy: Integer;
end;

Description

A generic type which holds dimensions of a rectangle, if not stated otherwise, dimensions are specified in pixels.


TStretchFilter

type TStretchFilter = (sfNearest, sfDraft, sfLinear, sfCosine, sfSpline, sfLanczos, sfMitchell);

Description

When the bitmap is scaled, these filters control how the colors are interpolated:

  • sfNearest is the fastest filter, although the quality of the stretched image is fair.
  • sfDraft is a complex resampler, meaning that it uses several different methods. For downsampling it uses row-column zoneshifting to preserve more details than sfNearest, however the quality is not as good as sfLinear. For upsampling it uses a linear interpolation method that may compromise details - this happens if both downsampling and upsampling is needed. sfDraft is ideal for preview fields and thumbnails. Please note, that the algorithm is not pixel-perfect, that why using a custom cliprect might result in a so called jitter-effect.
  • sfLinear is several times slower, but it produces more decent results in most cases.
  • sfCosine is almost equally fast as sfLinear, but it uses cosine interpolation, which produces a sharper image.
  • sfSpline is an approximation of spline interpolation, for some applications its result may be too smooth and blurry, but when using with large magnification factors, it usually yields better image compared to sfLinear.
  • sfLanczos generally produces the sharpest image (especially when downsampling), however sometimes can produce excessive "ringing" effect - this is the slowest filter.
  • sfMitchell is often considered as one of the best filters for enlarging images; generally not as sharp as Lanczos.

In some functions filters above sfLinear may not be applicable (for example in Transform), in this case the filter value will be substituted with sfLinear.

See Also

TCustomBitmap32.StretchFilter, StretchTransfer


TWrapMode

type TWrapMode = (wmClamp, wmRepeat, wmMirror);

Description

TWrapMode is the type for the WrapMode property in TBitmap32, which specifies how to wrapping pixel getters and setters should behave.

wmClamp will repeat the edge pixel if a pixel is read or written outside the bitmap's boundary.

wmRepeat will repeat the relative bitmap colors if it's outside of the bitmap's boundary (also referred to as 'seamless' and 'texture' mode).

wmMirror will mirror the pixel relative to the bitmap if it's outside the bitmap's boundary. This mode is useful for better perceptual results with spatial processing (like blurring).

See Also

TBitmap32, TCustomBitmap32.WrapMode


AlphaComponent

function AlphaComponent(Color32: TColor32): Integer;

Description

Extracts the alpha component from the parameter.

This function is provided for convenience and backward compatibility only. In performance-critical parts of your code use TColor32Entry typecasting or direct conversion:

Alpha := Color32 shr 24;

See Also

BlueComponent, GreenComponent, RedComponent, Color Types, Color Types


BlueComponent

function BlueComponent(Color32: TColor32): Integer;

Description

Extracts the blue component from the parameter.

This function is provided for convenience and backward compatibility only. In performance-critical parts of your code use TColor32Entry typecasting or direct conversion:

Blue := Color32 and $0000FF;

See Also

AlphaComponent, GreenComponent, RedComponent, Color Types, Color Types


Color32

function Color32(R, G, B: Byte; A: Byte = $FF): TColor32; overload;

This function combines its parameters into a 4-byte TColor32.

function Color32(WinColor: TColor): TColor32; overload;

This function provides conversion of TColor into TColor32.

The pixel format of 32-bit DIBs (ARGB) is different from that used in the standard TColor type (ABGR). Some standard windows colors are coded using special constants which are encoded into RGB form.

The alpha of the resulting color is set to $FF;

function Color32(Index: Byte; Palette: PPalette32): TColor32; overload;

This function simply picks the color value from the palette, same as

Result := Palette[Index];

See Also

Gray32, Color Types, Color Types, WinColor


Color32Components

function Color32Components(R, G, B, A: Boolean): TColor32Components;

Returns a set (TColor32Components) of TColor32Component from the provided parameters.

If all parameters are false, an empty set will be returned.

See Also

Color Types, Color Types


Color32ToRGB

procedure Color32ToRGB(Color32: TColor32; var R, G, B: Byte);

procedure Color32ToRGBA(Color32: TColor32; var R, G, B, A: Byte);

Both procedures split the Color32 parameter up into their respective components.

These procedures are provided for convenience only. Use direct conversion in performance-critical parts of your code:

Alpha := Color32 shr 24;

Red := (Color32 and $00FF0000) shr 16;

Green := (Color32 and $0000FF00) shr 8;

Blue := Color32 and $000000FF;


Creating Points

Point

function Point(X, Y: Integer): TPoint; overload;

function Point(const FP: TFloatPoint): TPoint; overload;

function Point(const FXP: TFixedPoint): TPoint; overload;

Constructs a point with integer coordinates, or converts it from the one with fixed/floating point coordinates by rounding them to nearest integers.

FloatPoint

function FloatPoint(X, Y: Single): TFloatPoint; overload;

function FloatPoint(const P: TPoint): TFloatPoint; overload;

function FloatPoint(const FXP: TFixedPoint): TFloatPoint; overload;

Provides construction and converstion of points with floating-point coordinates.

FixedPoint

function FixedPoint(X, Y: Integer): TFixedPoint; overload;

function FixedPoint(X, Y: Single): TFixedPoint; overload;

function FixedPoint(const P: TPoint): TFixedPoint; overload;

function FixedPoint(const FP: TFloatPoint): TFixedPoint; overload;

Provides construction and converstion of points with fixed-point coordinates

See Also

Point Types, Point Types, Point Types


Creating Rectangles

Rect

function MakeRect(L, T, R, B: Integer): TRect; overload;

function MakeRect(const FR: TFloatRect; Rounding: TRectRounding = rrClosest): TRect; overload;

function MakeRect(const FXR: TFixedRect; Rounding: TRectRounding = rrClosest): TRect; overload;

Provides construction and convertion of rectangles with integer coordinates.

FloatRect

function FloatRect(L, T, R, B: Single): TFloatRect; overload;

function FloatRect(const Rect: TRect): TFloatRect; overload;

function FloatRect(const FXR: TFixedRect): TFloatRect; overload;

Provides construction and convertion of rectangles with floating-point coordinates.

FixedRect

function FixedRect(L, T, R, B: TFixed): TFixedRect; overload;

function FixedRect(const Rect: TRect): TFixedRect; overload;

function FixedRect(const FR: TFloatRect): TFixedRect; overload;

Provides construction and convertion of rectangles with fixed-point coordinates.

See Also

Rectangle Types, Rectangle Types, Rectangle Types, TRectRounding


EqualRect

function EqualRect(const R1, R2: TRect): Boolean;

Description

Returns True if the rectangles are identical.

See Also

Rectangle Types


Fixed Point Math

Fixed

function Fixed(S: Single): TFixed; overload;

function Fixed(I: Integer): TFixed; overload;

A couple of TFixed constructors.

In case you don't want your program to loose time on extra function call, you can use another method of converting Integer to TFixed:

var

FX: TFixed;

begin

FX := IntVal shl 16;

...

end;

See Also

GR32_Math, TFixed


Gray32

function Gray32(Intensity: Byte; Alpha: Byte): TColor32;

Description

The action of Gray32(I, A) is the same as Color32(I, I, I, A). It just works faster.

See Also

AlphaComponent, BlueComponent, Color32, GreenComponent, RedComponent, Color Types


GreenComponent

function GreenComponent(Color32: TColor32): Integer;

Description

Extracts the green component from the parameter.

This function is provided for convenience and backward compatibility only. In performance-critical parts of your code use TColor32Entry typecasting or direct conversion:

Green := (Color32 and $0000FF00) shr 8;

See Also

AlphaComponent, BlueComponent, RedComponent, Color Types, Color Types


HSLtoRGB

function HSLtoRGB(H, S, L: Single): TColor32; overload;

function HSLtoRGB(H, S, L: Integer): TColor32; overload;

Description

Conversion from HSL to RGB color space. Each argument should normally be in [0…1] range for the float version and in the [0...255] range for the integer version, although the H value is automatically wrapped.

See Also

Gray32, RGBtoHSL, Color Types


InflateRect

procedure InflateRect(var R: TRect; Dx, Dy: Integer); overload;

procedure InflateRect(var FR: TFloatRect; Dx, Dy: Single); overload;

Description

Increases (or decreases if Dx, Dy negative) the width and height of the specified rectangle:

R.Left := R.Left - Dx;

R.Right := R.Right + Dx;

R.Top := R.Top - Dy;

R.Bottom := R.Bottom + Dy;

See Also

OffsetRect, Rectangle Types, Rectangle Types


Intensity

function Intensity(Color32: TColor32): Integer;

Description

Returns weighted intensity of the color, which is calculated as

I = R * 0.21 + G * 0.71 + B * 0.08;

See Also

Color32, Gray32, Color Types


IntersectRect

function IntersectRect(out Dst: TRect; const R1, R2: TRect): Boolean; overload;

function IntersectRect(out Dst: TFloatRect; const FR1, FR2: TFloatRect): Boolean; overload;

Description

Calculates intersection of the rectangles and writes result into Dst. Functions return True if rectangles intersect, otherwise it returns False and writes an empty rectangle into Dst, that is rectangle with all coortinates equal to 0.

See Also

Creating Rectangles, Rectangle Types, Rectangle Types


IsRectEmpty

function IsRectEmpty(const R: TRect): Boolean; overload;

function IsRectEmpty(const FR: TRect): Boolean; overload;

Description

Returns True if the rectangle is empty, that is its width or height is not positive.

See Also

Rectangle Types


OffsetRect

procedure OffsetRect(var R: TRect; Dx, Dy: Integer); overload;

procedure OffsetRec(var FR: TFloatRect; Dx, Dy: Single); overload;

Description

Use thise functions to shift rectangles. Dx and Dy parameters specify the distance.

See Also

InflateRect, Rectangle Types, Rectangle Types


PtInRect

function PtInRect(const R: TRect; const P: TPoint): Boolean;

Description

Returns True if the point lies inside the specified rectangle.

See Also

Point Types, Rectangle Types


RedComponent

function RedComponent(Color32: TColor32): Integer;

Description

Extracts the red component from the parameter.

This function is provided for convenience and backward compatibility only. In performance-critical parts of your code use TColor32Entry typecasting or direct conversion:

Red := (Color32 and $00FF0000) shr 16;

See Also

AlphaComponent, BlueComponent, GreenComponent, Color Types, Color Types


RGBtoHSL

procedure RGBtoHSL(RGB: TColor32; var H, S, L : Single); overload;

procedure RGBtoHSL(RGB: TColor32; var H, S, L : Byte); overload;

Description

Conversion from RGB to HSL color space. The H, S and L components are returned in corresponding var parameters ranging from 0 to 1 for the float version and 0 to 255 for the byte version.

See Also

Gray32, HSLtoRGB, Color Types


SetAlpha

function SetAlpha(Color32: TColor32; NewAlpha: Integer): TColor32;

Description

Returns a color with the new alpha channel. This function automatically performs clipping of the NewAlpha parameter to [0…255] range.

See Also

Color Types


SetGamma

procedure SetGamma(Gamma: Single = 0.7);

Description

Updates gamma/shape correction table.

Pixel and line antialiasing produces much better results with correction of opacities for partially covered pixels. This accounts both for monitor gamma and for pixel shape correction.

Use this function to update the internal gamma-correction table which is used in pixel and line rasterization.

The default value of 0.7 works fine in most cases.


WinColor

function WinColor(Color32: TColor32): TColor;

Description

Provides conversion of the TColor32 value back into TColor. The highest-order byte (Alpha channel) of resulting color is assigned the $FF value.

See Also

Color32, Color Types


WinPalette

function WinPalette(P: TPalette32): HPALETTE;

Description

The provided TPalette32 fixed-size buffer of color values is converted into the Win32 API equivalent HPALETTE handle definition of a palette with 256 32-bit color entries.

See Also

Color32, Color Types


Area Information Flags

The Area Information Flags are used in the TAreaChangedEvent to further describe the shape of the changed area.

Currently Graphics32 defines these types:

const

// common cases

AREAINFO_RECT = $80000000;

AREAINFO_LINE = $40000000; // 24 bits for line width in pixels...

AREAINFO_ELLIPSE = $20000000;

AREAINFO_ABSOLUTE = $10000000;

AREAINFO_MASK = $FF000000;

See Also

TAreaChangedEvent


Color Constants

Color constants specify some predefined values of TColor32 type.

Their names are similar to standard ones, they just have a '32' postfix:

Constant | Value
clBlack32 | $FF000000
clDimGray32 | $FF3F3F3F
clGray32 | $FF7F7F7F
clLightGray32 | $FFBFBFBF
clWhite32 | $FFFFFFFF
clMaroon32 | $FF7F0000
clGreen32 | $FF007F00
clOlive32 | $FF7F7F00
clNavy32 | $FF00007F
clPurple32 | $FF7F007F
clTeal32 | $FF007F7F
clRed32 | $FFFF0000
clLime32 | $FF00FF00
clYellow32 | $FFFFFF00
clBlue32 | $FF0000FF
clFuchsia32 | $FFFF00FF
clAqua32 | $FF00FFFF

In addition, Graphics32 defines a few colors with 50% transparency:

Constant | Value
clTrWhite32 | $7FFFFFFF
clTrBlack32 | $7F000000
clTrRed32 | $7FFF0000
clTrGreen32 | $7F00FF00
clTrBlue32 | $7F0000FF

See Also

Color Types


G32Version

The Graphics32Version constant is a string that holds version number of the library.

The version number is a simple string which may optionally include sub-version literal, e.g. '0.98a', '0.99', '1.0' etc.


TBackend

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

Description

The TBackend class is the base class for all back-end classes. It defines the bare minimum functionality required to implement a new back-end class. It provides simplified management of surface (re-)allocation and deallocation by implementing ChangeSize in a convenient way. New back-ends shall implement the abstract protected methods InitializeSurface and FinalizeSurface.

It also implements the necessary Assign method for switching back-ends while preserving the surface's contents.

Reference

Fields | Methods | Properties | Events
In TBackend:
 | Assign | Bits | OnChanging
 | ChangeSize |  |
 | Changing |  |
 | Clear |  |
 | Create |  |
 | Destroy |  |
 | Empty |  |
 | FinalizeSurface |  |
 | InitializeSurface |  |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |


Assign

TBackend.Assign

procedure Assign(Source: TPersistent); override;

Description

Handles copying the source surface defined by the Source parameter to the current instance.
Internally it calls ChangeSize on the current back-end instance to set the new size. Then it copies the content of the source surface to the allocated surface via MoveLongword.
This method is used during switching of the back-end classes in TCustomBitmap32.


ChangeSize

TBackend.ChangeSize

procedure ChangeSize(var Width, Height: Integer; NewWidth, NewHeight: Integer; ClearBuffer: Boolean = True); virtual; abstract;

Description

ChangeSize shall initialize the surface with the dimensions of NewWidth x NewHeight both measured in pixels. Each pixel has to be 4 byte (ARGB) in size. The allocated memory has to be contiguous with the stride being the length of NewWidth. GR32 currently does not support stride lengths different from the width of the new surface. The pointer to the allocated memory has to be written to the protected member FBits.
The ClearBuffer parameter determines whether clearing the buffer is required or not.

Before tearing down the old surface ChangeSize needs to call the Changing method to indicate the destructive change. Finally it has to call Changed.

Width and Height shall contain the dimension of the new surface that was actually allocated. If the surface could not be allocated both parameter have to be zero.

New back-end classes need to implement this method to do their internal allocation of memory for the surface.

See Also

TNotifiablePersistent.Changed, Changing, FinalizeSurface, InitializeSurface


Changing

TBackend.Changing

procedure Changing;

Description

Calls the OnChanging event.

Descendants of TBackend call Changing before making changes to their data or properties that are potentially destructive.

See Also

OnChanging, TBackend


Clear

TBackend.Clear

procedure Clear; virtual;

Description

Resets the back-end's internal state and deallocates the back-end surface by calling ChangeSize with NewWidth and NewHeight set to zero.

See Also

ChangeSize


Create

TBackend.Create

constructor Create; overload; override;

constructor Create(Owner: TCustomBitmap32); reintroduce; overload; virtual;

Description

Creates and initializes an instance of TBackend.

If Owner is specified the new back-end instance is automatically assigned to the TCustomBitmap32 instance. The existing back-end of the bitmap instance will be replaced and surface data is transfered to the new back-end instance via the Assign method.

Subclasses may extend the constructor with their specific parameters.

For an usage example of the constructor please refer to the additional topic Back-ends in this documentation.

See Also

Assign, Back-Ends, TBackend, TCustomBitmap32


Destroy

TBackend.Destroy

destructor Destroy; override;

Description

Destroys the back-end instance and frees all associated memory.

Do not call Destroy directly, use Free method instead.


Empty

TBackend.Empty

function Empty: Boolean; virtual; abstract;

Description

Shall return True if the back-end is empty. Subclasses have to implement this method to indicate whether they are empty depending on their internal state.
By design back-ends do not need to save the size of the allocated surface as this is handled by the owner bitmap. Thus, the bitmap instance will call this method to determine if there are any other conditions aside from the surface size, which is checked in TCustomMap.Empty.

See Also

TCustomMap.Empty


FinalizeSurface

TBackend.FinalizeSurface

procedure FinalizeSurface; virtual; abstract;

Description

Finalizes the internal surface memory.
This method is called internally by ChangeSize.

New back-end classes need to implement this method to do their internal de-allocation of memory for the surface.

See Also

ChangeSize, InitializeSurface


InitializeSurface

TBackend.InitializeSurface

procedure InitializeSurface(NewWidth, NewHeight: Integer; ClearBuffer: Boolean); virtual; abstract;

Description

Initializes the surface with the dimensions of NewWidth x NewHeight both measured in pixels. Each pixel has to be 4 byte (ARGB) in size. The allocated memory has to be contiguous with the stride being the length of NewWidth. GR32 currently does not support stride lengths different from the width of the new surface. The pointer to the allocated memory has to be written to the protected member FBits.
The ClearBuffer parameter determines whether clearing the buffer is required or not.
This method is called internally by the default ChangeSize method implementation of TBackend.

New back-end classes need to implement this method to do their internal allocation of memory for the surface.

See Also

ChangeSize, FinalizeSurface, TBackend


Bits

TBackend.Bits

property Bits: PColor32Array; // Read-only

type TColor32Array = array [0..0] of TColor32;

type PColor32Array = ^TColor32Array;

Description

The bits property contains the address of the first (top-left) pixel in the back-end's surface. If the bitmap is not allocated (width or height is zero), the returned address is nil.

Subclassed back-ends need to set the protected member FBits to the of beginning of the surfaces memory. This is done InitializeSurface.

See Also

TCustomBitmap32.Bits, InitializeSurface, Color Types, Color Types


OnChanging

TBackend.OnChanging

property OnChanging: TNotifyEvent;

Description

OnChanging is triggered immediately before the back-end changes. Typically TCustomBitmap32 or TBitmap32 will use this event to do a cleanup of held resources (fonts etc.).

See Also

TNotifiablePersistent.Changed


TBitmap32

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TCustomMap

|

TCustomBitmap32

Description

TBitmap32 extends TCustomBitmap32 with various methods and properties specific to the operating system's graphic subsystem. It provides methods for drawing on a device context (DC).

TBitmap32 does not implement its own low-level streaming or low-level file loading/saving. Instead, it uses streaming methods of temporal TBitmap or TPicture objects. This is an obvious performance penalty, however such approach allows using third-party libraries, which extend TGraphic class for various image formats support (JPEG, TGA, TIFF, GIF, PNG, etc.). When you install them, TBitmap32 will automatically obtain support for new image file formats in design time and in run time.

TBitmap32 overrides Assign and AssignTo methods (inherited from TPersistent) to provide compatibility with standard objects: TBitmap, TPicture and TClipboard in both directions. The design-time streaming to and from *.dfm files, inherited from TPersistent, is supported, but its realization is different from streaming with other stream types (See the source code for details).

Reference

Methods | Properties | Events
In TBitmap32:
CanvasAllocated | BitmapHandle | OnHandleChanged
DeleteCanvas | BitmapInfo |
HandleChanged | Canvas |
LoadFromResourceID | Font |
LoadFromResourceName | Handle |
RenderText | Pixmap |
TextExtent | PixmapChanged |
TextHeight |  |
TextOut |  |
TextWidth |  |
UpdateFont |  |
In TCustomBitmap32:
BeginMeasuring | Backend | OnAreaChanged
Clear | Bits | OnPixelCombine
Create | Clipping |
Destroy | ClipRect |
Draw | CombineMode |
DrawTo | DrawMode |
Empty | MasterAlpha |
EndMeasuring | MeasuringMode |
FillRect | OuterColor |
FlipHorz | PenColor |
FlipVert | Pixel |
FrameRect | PixelPtr |
GetStippleColor | Resampler |
HorzLine | ResamplerClassName |
Line | ScanLine |
LineTo | StippleCounter |
LoadFromFile | StippleStep |
LoadFromStream | StretchFilter |
MoveTo | WrapMode |
RaiseRectTS |  |
ResetAlpha |  |
ResetClipRect |  |
Roll |  |
Rotate |  |
SaveToFile |  |
SaveToStream |  |
SetPixel |  |
SetSize |  |
SetStipple |  |
VertLine |  |
In TCustomMap:
Delete | Height | OnResize
Resized | Width |
In TThreadPersistent:
Lock | LockCount |
Unlock |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
EndUpdate |  |


CanvasAllocated

TBitmap32.CanvasAllocated

function CanvasAllocated: Boolean;

Description

Indicates whether the internal Canvas has been allocated.

See Also

Canvas, RenderText, UpdateFont


DeleteCanvas

TBitmap32.DeleteCanvas

procedure DeleteCanvas;

Description

Destroys the internal Canvas object.

See Also

Canvas, CanvasAllocated, RenderText


HandleChanged

TBitmap32.HandleChanged

procedure TBitmap32.HandleChanged; virtual; // protected

Description

This method is called every time the device handle of the bitmap is changed. It calls the OnHandleChanged event.

See Also

Handle, Naming Conventions, OnHandleChanged


LoadFromResourceID

TBitmap32.LoadFromResourceID

procedure LoadFromResourceID(Instance: THandle; ResID: Integer);

Description

Loads an image from a resource. Instance is the handle of the module that contains the resource. ResID is the resource ID for the bitmap

See Also

TCustomBitmap32.LoadFromFile, LoadFromResourceName, TCustomBitmap32.LoadFromStream


LoadFromResourceName

TBitmap32.LoadFromResourceName

procedure LoadFromResourceName(Instance: THandle; const ResName: string);

Description

Loads an image from a resource. Instance is the handle of the module that contains the resource. ResName is the name of the resource to load.

See Also

TCustomBitmap32.LoadFromFile, LoadFromResourceID, TCustomBitmap32.LoadFromStream


RenderText

TBitmap32.RenderText

procedure RenderText( X, Y: Integer; const Text: String; AALevel: Integer; Color: TColor32);

procedure RenderTextW( X, Y: Integer; const Text: Widestring; AALevel: Integer; Color: TColor32);

Description

The RenderText or RenderTextW (the Unicode-Version) method draws a string of characters. This method is much slower compared to TextOut functions, however it supports antialiasing and transparency. AALevel specifies how the text is antialiased. If it is zero, no antialiasing is performed, the value of 4 corresponds to a maximum quality.

Note, that quality of the text is also influenced by the system font antialiasing.

This method draws a string using current Font, but it ignores the Font.Color property, substituting it with the Color parameter.

Please note that the CLX versions of the non-Unicode methods do also default to Widestring because that is the native QT string format.

See Also

Font, Examples, Color Types, TextExtent, TextOut


TextExtent

TBitmap32.TextExtent

function TextExtent(const Text: String): TSize;

function TextExtentW(const Text: Widestring): TSize;

Description

Returns the width and height, in pixels, of a string rendered in the current Font.

Note, that the size returned by this function may differ from the actual width of the text produced by RenderText function, especially when using raster fonts.

Please note that the CLX versions of the non-Unicode methods do also default to Widestring because that is the native QT string format.

See Also

Font, RenderText, TextHeight, TextOut, TextWidth, TSize


TextHeight

TBitmap32.TextHeight

function TextHeight(const Text: String): Integer;

function TextHeightW(const Text: Widestring): Integer;

Description

Returns the height, in pixels, of a string rendered in the current Font.

Please note that the CLX versions of the non-Unicode methods do also default to Widestring because that is the native QT string format.

See Also

Font, RenderText, TextExtent, TextOut, TextWidth


TextOut

TBitmap32.TextOut

procedure TextOut(X, Y: Integer; const Text: String); overload;

procedure TextOutW(X, Y: Integer; const Text: Widestring); overload;

procedure TextOut(X, Y: Integer; const ClipRect: TRect; const Text: String); overload;

procedure TextOutW(X, Y: Integer; const ClipRect: TRect; const Text: Widestring); overload;

procedure TextOut(DstRect: TRect; const Flags: Cardinal; const Text: String); overload;

procedure TextOutW(DstRect: TRect; const Flags: Cardinal; const Text: Widestring); overload;

Description

Use TextOut or TextOutW (the Unicode version) to write a string onto the bitmap. The string will be written using current Font.

Use the TextExtent method to determine the space occupied by the text in the image. TextOut does not support transparent text colors.

The second version performs clipping of a text to the ClipRect rectangle.

The last version provides the most flexible text formatting. See description of DrawText function in 'Win32 Developer Reference' help file for information on Flags and their function.

Special Note for CLX users:

Since CLX is based on the QT library rather than the native Win API the flags used in the last two functions are somewhat different from the Win32 flags. You can get more information on the QT specific flags here and here. However, to make it easier for you, we have provided some basic mappings that will work in QT just as their Win API counterparts:

DT_LEFT, DT_RIGHT, DT_TOP, DT_BOTTOM, DT_CENTER, DT_VCENTER, DT_EXPANDTABS, DT_NOCLIP, DT_WORDBREAK, DT_SINGLELINE

However, the following flags are missing because there is no equivalent value in QT at this time:

DT_CALCRECT, DT_EDITCONTOL, DT_END_ELLIPSIS and DT_PATH_ELLIPSIS, DT_EXTERNALLEADING, DT_MODIFYSTRING, DT_NOPREFIX, DT_RTLREADING, DT_TABSTOP

Please note that the CLX versions of the non-Unicode methods do also default to Widestring because that is the native QT string format.

See Also

Font, RenderText, TextExtent, TextHeight, TextWidth, Rectangle Types


TextWidth

TBitmap32.TextWidth

function TextWidth(const Text: String): Integer;

function TextWidthW(const Text: Widestring): Integer;

Description

Returns the width, in pixels, of a string rendered in the current Font.

Please note that the CLX versions of the non-Unicode methods do also default to Widestring because that is the native QT string format.

See Also

Font, RenderText, TextExtent, TextHeight, TextOut


UpdateFont

TBitmap32.UpdateFont

procedure UpdateFont;

Description

Use this method before calling the Windows API functions that handle text output. It will synchronize the device font object with the Font property. You do not have to call UpdateFont when using text output methods of TBitmap32 since they call UpdateFont automatically.

See Also

Font, TBitmap32


BitmapHandle

TBitmap32.BitmapHandle

property BitmapHandle: HBITMAP; // read-only;

Description

Returns current bitmap handle. See HBITMAP in Windows SDK documentation for more information.

Note, this property is not the same as Handle, which returns device handle (HDC).

This property is only available in the VCL version. For CLX use the property Pixmap instead.

See Also

Handle, TCustomBitmap32.PixelPtr, Pixmap, TCustomBitmap32.ScanLine


BitmapInfo

TBitmap32.BitmapInfo

property BitmapInfo: TBitmapInfo; // read-only;

Description

Returns a BITMAPINFO record corresponding to a current DIB data. See BITMAPINFO in Windows SDK documentation for more information.

This property is only available in the VCL version.

See Also

TCustomBitmap32.PixelPtr, TCustomBitmap32.ScanLine


Canvas

TBitmap32.Canvas

property Canvas: TCanvas; // read-only;

Description

Returns current Canvas instance. You can use that to draw onto the bitmap. However the methods provided by TCanvas are mostly slower than using their native Bitmap32 counterparts. So try to avoid the usage of Canvas where possible.

Special note for CLX users: Due to the way QT is handling image and bitmap data, please try to avoid using only single Canvas operations. Every time you access the Canvas, the internal QImage is unavoidably copied to a QPixmap representative and copied back once the Bits property or any other internal method is accessed. So, if you access the Bits and Canvas properties in short interval after each other, that poses a heavy performance hit due to copying the QImage to QPixmap back and forth.


Font

TBitmap32.Font

property Font: TFont;

Description

Specifies the current font used by text output functions.

See Also

RenderText, TextOut, UpdateFont


Handle

TBitmap32.Handle

This following only applies to the VCL version of Graphics32:

property Handle: HDC; // read-only

Description

Provides device handle of the contained DIB.

This handle may be used in low-level Windows API calls or, for example, to attach a TCanvas object to TBitmap32:

var

Canvas: TCanvas;

begin

Canvas := TCanvas.Create; // create a new independent TCanvas object

try

Canvas.Handle := Bitmap32.Handle; // attach it to the Bitmap32 object

Canvas.Pen.Color := clRed; // use standard TCanvas methods for drawing

Canvas.Brush.Color := clGreen;

Canvas.Ellipse(10, 10, 60, 40);

finally

Canvas.Free;

end;

end;

Handle contains zero, if the bitmap is empty (width or height is zero), and its value can change after resizing.

This example is just a simple illustration of using the Handle property. For more information on using the TCanvas object with TBitmap32, see the Canvas property.

This following only applies to the CLX version of Graphics32:

property Handle: QPainterH; // read-only

Description

This provides a pointer to the current instance of the QPainterH in TBitmap32.

You can use this QPainter instance in external functions. However please notice, that the QPainter is not associated with the QPixmap of TBitmap32. You'll have to call QPainter_begin and QPainter_end manually to do so. See the QT docs for more information on this topic.

See Also

Canvas, TBitmap32


Pixmap

TBitmap32.Pixmap

property Pixmap: QPixmapH; // read-only;

Description

Returns a pointer to the current Pixmap instance. You can use that if you're working directly with QT related methods.

Important Note: Due to the nature of QT handling images and bitmap information, there is a need to notify TBitmap32 about changes you made to the QPixmap. You can use the PixmapChanged property to do so.
This will copy the Pixmap content as soon as the Bits property is accessed or some internal function is accessing the image data directly. This will make sure that the content is copied from the QPixmap to the internal QImage in TBitmap32.

This property is only available in the CLX version. For VCL use the property BitmapHandle instead.

See Also

BitmapHandle


PixmapChanged

TBitmap32.PixmapChanged

property PixmapChanged: Boolean;

Description

Returns whether the current QPixmap instance has changed or not. You can use that if you're working directly with QT related methods.

Important Note: Due to the nature of QT handling images and bitmap information, there is a need to notify TBitmap32 about changes you made to the QPixmap. You can use this property to do so.
This will copy the QPixmap content as soon as the Bits property is accessed or some internal function is accessing the image data directly. This will make sure that the content is copied from the QPixmap to the internal QImage in TBitmap32.

This property is only available in the CLX version.

See Also

Pixmap


OnHandleChanged

TBitmap32.OnHandleChanged

property OnHandleChanged: TNotifyEvent;

Description

This event is called when the HDC/QPainterH of property Handle changed. Use this event to customize handling of such events.

See Also

Handle


TCustomBitmap32

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TCustomMap

Description

TCustomBitmap32 is the central class in the Graphics32 library. It manages a single 32-bit device-independent bitmap (DIB) and provides methods for drawing on it and combining it with other DIBs.

Since TCustomBitmap32 is a descendant of TThreadPersistent, it inherits its locking mechanism and it may be used in multi-threaded applications.

Change Notification

Change notification events (OnChange, OnResize), inherited from TNotifiablePersistent and TCustomMap are generated by most drawing/resizing etc. functions with a few exceptions. Due to performance considerations the following functions are not accompanied with event generation:

  • Pixel-based operations (SetPixelT, SetPixelF...);
  • HorzLine* and VertLine* functions;

If necessary, the OnChange event may be generated explicitly by calling the Changed methods.

Normally, if the bitmap is a part of some container (TImage32, TBitmapLayer, etc.), its change notification events are linked to the container, causing repaint operations. When making several simultaneous changes, it may be beneficial to enclose them in BeginUpdate…EndUpdate block followed by the Changed call to reduce the amount of repaintings of the container.

Reference

Fields | Methods | Properties | Events
In TCustomBitmap32:
 | BeginMeasuring | Backend | OnAreaChanged
 | Clear | Bits | OnPixelCombine
 | Create | Clipping |
 | Destroy | ClipRect |
 | Draw | CombineMode |
 | DrawTo | DrawMode |
 | Empty | MasterAlpha |
 | EndMeasuring | MeasuringMode |
 | FillRect | OuterColor |
 | FlipHorz | PenColor |
 | FlipVert | Pixel |
 | FrameRect | PixelPtr |
 | GetStippleColor | Resampler |
 | HorzLine | ResamplerClassName |
 | Line | ScanLine |
 | LineTo | StippleCounter |
 | LoadFromFile | StippleStep |
 | LoadFromStream | StretchFilter |
 | MoveTo | WrapMode |
 | RaiseRectTS |  |
 | ResetAlpha |  |
 | ResetClipRect |  |
 | Roll |  |
 | Rotate |  |
 | SaveToFile |  |
 | SaveToStream |  |
 | SetPixel |  |
 | SetSize |  |
 | SetStipple |  |
 | VertLine |  |
In TCustomMap:
 | Delete | Height | OnResize
 | Resized | Width |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

TBitmapLayer, TCustomMap, TImage32, TNotifiablePersistent, TThreadPersistent


BeginMeasuring

TCustomBitmap32.BeginMeasuring

procedure BeginMeasuring(const Callback: TAreaChangedEvent);

Description

Attaches a callback method to the OnAreaChanged event and switches the bitmap into measuring mode. The event handler previously attached to the OnAreaChanged event is preserved and will be reset once measuring is stopped by calling EndMeasuring.

See Also

EndMeasuring, Repaint Optimization, OnAreaChanged, TAreaChangedEvent


Clear

TCustomBitmap32.Clear

procedure Clear; overload;

procedure Clear(FillColor: TColor32); overload;

Description

Fills the entire bitmap with FillColor. If there is no argument specified, method uses clBlack32 ($FF000000).

See Also

TCustomMap.Delete, Color Types


Create

TCustomBitmap32.Create

constructor Create; override;

Description

Creates and initializes an instance of TCustomBitmap32.

After calling the inherited constructor, Create initializes the following properties:

  • DrawMode to dmOpaque;
  • MasterAlpha to 255 ($FF);
  • OuterColor to transparent black: $00000000;
  • PenColor to clWhite32;
  • StippleCounter to 0;
  • StippleStep to 1.0;
  • StretchFilter to sfNearest;

See Also

DrawMode, MasterAlpha, OuterColor, PenColor, StippleCounter, StippleStep, TCustomBitmap32, TStretchFilter


Destroy

TCustomBitmap32.Destroy

destructor Destroy; override;

Description

Destroys the bitmap object and frees all associated memory.

Do not call Destroy directly, use Free method instead.


Draw

TCustomBitmap32.Draw

procedure Draw(DstX, DstY: Integer; Src: TCustomBitmap32); overload;

procedure Draw(DstX, DstY: Integer; const SrcRect: TRect; Src: TCustomBitmap32); overload;

procedure Draw(const DstRect, SrcRect: TRect; Src: TCustomBitmap32); overload;

Description

Renders the image specified by Src parameter (or part of it specified by SrcRect parameter) at the location given by the coordinates (DstX, DstY) or the DstRect rectangle.

The method provides both: block transfer (versions with DstX, DstY parameters) and stretching (versions with DstRect parameter).

The method uses Src.DrawMode do determine how it should be blended with the background, and if stretching, Src.StretchFilter specifies how the image should be stretched.

The Dst parameter must not be necessarily some other bitmap. In fact, it is possible to copy/stretch areas inside the same bitmap that calls the Draw method. However, in this case, if source and destination areas intersect, the result is not specified (this is a limitation of the current version).

See Also

BlockTransfer, DrawMode, DrawTo, StretchFilter, StretchTransfer, TCustomBitmap32, Rectangle Types


DrawTo

TCustomBitmap32.DrawTo

procedure DrawTo(Dst: TCustomBitmap32); overload;

procedure DrawTo(Dst: TCustomBitmap32; DstX, DstY: Integer); overload;

procedure DrawTo(Dst: TCustomBitmap32; DstX, DstY: Integer; const SrcRect: TRect); overload;

procedure DrawTo(Dst: TCustomBitmap32; const DstRect: TRect); overload;

procedure DrawTo(Dst: TCustomBitmap32; const DstRect, SrcRect: TRect); overload;

Description

The DrawTo method renders the bitmap (or part of it specified by SrcRect parameter) onto another bitmap specified by Dst parameter. It works similar to Draw method but instead of copying data from some other source, the bitmap renders itself to destination object. See the Draw description for details.

See Also

Draw, TCustomBitmap32, Rectangle Types


Empty

TCustomBitmap32.Empty

function Empty: Boolean; override;

Description

Returns True if the bitmap is empty, that is Width or Height is zero.

See Also

TCustomMap.Height, TCustomMap.Width


EndMeasuring

TCustomBitmap32.EndMeasuring

procedure EndMeasuring;

Description

Stops the measuring mode and switches the bitmap back into normal operation mode. If there was an event handler previously attached to the OnAreaChanged event it is restored.

See Also

BeginMeasuring, Repaint Optimization, OnAreaChanged


FillRect

TCustomBitmap32.FillRect

procedure FillRect(X1, Y1, X2, Y2: Integer; Value: TColor32);

procedure FillRectS(X1, Y1, X2, Y2: Integer; Value: TColor32); overload;

procedure FillRectT(X1, Y1, X2, Y2: Integer; Value: TColor32);

procedure FillRectTS(X1, Y1, X2, Y2: Integer; Value: TColor32); overload;

procedure FillRectS(const ARect: TRect; Value: TColor32); overload;

procedure FillRectS(const ARect: TRect; Value: TColor32); overload;

Description

Fills the rectangle with a specified color. Methods with 'S' postfix provide necessary clipping to bitmap boundaries, versions without 'S' must be supplied with valid parameters and X2 > X1; Y2 > Y1.

The function fills the rectangle up to, but not including the right column and bottom row. When X2 <= X1 or Y2 <= Y1, nothing is drawn.

See Also

FrameRect, Naming Conventions, Color Types


FlipHorz

TCustomBitmap32.FlipHorz

procedure FlipHorz(Dst: TBitmap32);

Description

FlipHorz flips the image horizontally. When Dst parameter is specified, the transformed version of the image is copied into Dst, otherwise the procedure performs the in-place flipping.

See Also

FlipVert, TCustomBitmap32


FlipVert

TCustomBitmap32.FlipVert

procedure FlipVert(Dst: TBitmap32);

Description

FlipVert flips the image vertically. When Dst parameter is specified, the transformed version of the image is copied into Dst, otherwise the procedure performs the in-place flipping.

See Also

FlipHorz, TCustomBitmap32


FrameRect

TCustomBitmap32.FrameRect

procedure FrameRectS(X1, Y1, X2, Y2: Integer; Value: TColor32); overload;

procedure FrameRectTS(X1, Y1, X2, Y2: Integer; Value: TColor32); overload;

procedure FrameRectS(const ARect: TRect; Value: TColor32); overload;

procedure FrameRectTS(const ARect: TRect; Value: TColor32); overload;
procedure FrameRectTSP(X1, Y1, X2, Y2: Integer);

Description

Draws a rectangle frame. Row with X2 coordinate and column with Y2 coordinate are excluded.

If X2 <= X1 or Y2 <= Y1, the function does not draw the rectangle.

FrameRectTSP version supports line patterns.

See Also

FillRect, LineTo, Naming Conventions, Color Types


GetStippleColor

TCustomBitmap32.GetStippleColor

function GetStippleColor: TColor32;

Description

Returns color corresponding to the current counter position in stipple pattern. If the counter step is fractional, returned color will be interpolated. Calling GetStippleColor automatically changes the StippleCounter value by StippleStep.

See Also

Line Patterns, SetStipple, StippleCounter, StippleStep, Color Types


HorzLine

TCustomBitmap32.HorzLine

procedure HorzLine(X1, Y, X2: Integer; Value: TColor32);

procedure HorzLineS(X1, Y, X2: Integer; Value: TColor32);

procedure HorzLineT(X1, Y, X2: Integer; Value: TColor32);

procedure HorzLineTS(X1, Y, X2: Integer; Value: TColor32);

procedure HorzLineTSP(X1, Y, X2: Integer);

Description

Draws a horizontal line from (X1,Y) to (X2, Y). The last point is always included.

These functions works faster compared to Line (I think HorzLine is the fastest line drawing function in the world :) . In versions with 'S' postfix necessary clipping to a bitmap coordinate range is provided. In versions without 'S' postfix, the X1 value should be less than or equal to X2.

HorzLineTSP uses a stipple pattern to vary the color along the line.

See Also

Line, Line Patterns, Naming Conventions, Color Types, VertLine


Line

TCustomBitmap32.Line

procedure Line(X1, Y1, X2, Y2: Integer; Value: TColor32; L: Boolean = False);

procedure LineS(X1, Y1, X2, Y2: Integer; Value: TColor32; L: Boolean = False);

procedure LineT(X1, Y1, X2, Y2: Integer; Value: TColor32; L: Boolean = False);

procedure LineTS(X1, Y1, X2, Y2: Integer; Value: TColor32; L: Boolean = False);

procedure LineA(X1, Y1, X2, Y2: Integer; Value: TColor32; L: Boolean = False);

procedure LineAS(X1, Y1, X2, Y2: Integer; Value: TColor32; L: Boolean = False);

procedure LineX(X1, Y1, X2, Y2: TFixed; Value: TColor32; L: Boolean = False);

procedure LineXS(X1, Y1, X2, Y2: TFixed; Value: TColor32; L: Boolean = False);

procedure LineF(X1, Y1, X2, Y2: Single; Value: TColor32; L: Boolean = False);

procedure LineFS(X1, Y1, X2, Y2: Single; Value: TColor32; L: Boolean = False);

procedure LineXP(X1, Y1, X2, Y2: Single; L: Boolean = False);

procedure LineXSP(X1, Y1, X2, Y2: Single; L: Boolean = False);

procedure LineFP(X1, Y1, X2, Y2: Single; L: Boolean = False);

procedure LineFSP(X1, Y1, X2, Y2: Single; L: Boolean = False);

Description

Draws a line from (X1,Y1) to (X2,Y2). Methods with 'S' postfix perform necessary pixel-perfect clipping to a bitmap boundary or clipping rectangle.

LineA and LineAS use modified versions of Bresenham’s algorithm (also known as Wu’s antialiasing), modified to support line transparency and pixel shape/gamma correction.

LineX/F/XS/FS functions use my own algorithm for antialiasing. Line ends have fixed- or floating-point coordinates. These methods work approximately 2–2.5 times slower than LineA and LineAS.

The last optional parameter (L) determines if the last point (X2,Y2) has to be drawn. It is useful in some cases to leave that point empty, especially when drawing sequences of transparent and/or antialiased lines. By default, Line methods don’t render the last point.

LineXP/FP/XSP/FXP draw antialiased lines with support for color patterns.

See Also

HorzLine, LineTo, MoveTo, Naming Conventions, Color Types, VertLine


LineTo

TCustomBitmap32.LineTo

procedure LineToS(X, Y: Integer);

procedure LineToTS(X, Y: Integer);

procedure LineToAS(X, Y: Integer);

procedure LineToXS(X, Y: TFixed);

procedure LineToFS(X, Y: Single);

procedure LineToXSP(X, Y: TFixed);

procedure LineToFSP(X, Y: Single);

Description

LineTo* methods are similar to TCanvas.LineTo. The line is drawn from the current raster position, to the position specified by X and Y parameters excluding the last point. Then raster position is shifted to (X, Y) point.

The line is drawn with the color specified in PenColor property. 'S', 'TS', and 'AS' versions use and update integer integer raster position, while 'FS' and 'XS' versions use and update independent fixed-point raster position.

LineToXSP and LineToFSP do not use PenColor, instead, they draw a line using currend stipple pattern.

To start a new line or sequence of lines, use MoveTo methods.

See Also

Line, Line Patterns, MoveTo, Naming Conventions, PenColor, TFixed


LoadFromFile

TCustomBitmap32.LoadFromFile

procedure LoadFromFile(const FileName: string);

Description

Loads an image from a file. This method uses a temporal TPicture object to load data and will succeed with any format supported by TPicture.

See Also

Examples, LoadFromStream, SaveToFile


LoadFromStream

TCustomBitmap32.LoadFromStream

procedure LoadFromStream(Stream: TStream);

Description

Loads an image from a stream. This method uses a temporal TPicture object to load data and will succeed with any format supported by TPicture.

See Also

LoadFromFile, SaveToStream


MoveTo

TCustomBitmap32.MoveTo

procedure MoveTo(X, Y: Integer);

procedure MoveToX(X, Y: TFixed);

procedure MoveToF(X, Y: Single);

Description

Shifts current raster to specified position, analogous to MoveTo method of standard TCanvas.

Each bitmap maintains separate raster positions for integer and fixed point coordinates. MoveTo affects the integer raster position, while MoveToX and MoveToF affect the fixed-point raster position.

Raster position is applicable only to MoveTo, LineTo methods and some polygon drawing routines, which use it internally, it is not changed neither by Line methods nor by any other method.

See Also

Line, LineTo, Naming Conventions, TFixed


RaiseRectTS

TCustomBitmap32.RaiseRectTS

procedure RaiseRectTS(X1, Y1, X2, Y2: Integer; Contrast: Integer);

Description

This function draws a raised or recessed frame. The contrast property is an integer value ranging from –100 to +100.

See Also

FrameRect, Naming Conventions


ResetAlpha

TCustomBitmap32.ResetAlpha

procedure ResetAlpha; overload;

procedure ResetAlpha(const AlphaValue: Byte); overload;

Description

Resets the alpha channel of the entire bitmap either to $FF or the value defined by AlphaValue.


ResetClipRect

TCustomBitmap32.ResetClipRect

procedure ResetClipRect;

Description

Resets the clipping rect to the current dimensions of the bitmap.


Roll

TCustomBitmap32.Roll

procedure Roll(Dx, Dy: Integer; FillBack: Boolean; FillColor: TColor32);

Description

Use Roll to scroll the whole bitmap Dx pixels right and Dy pixels down.

Dx an Dy may be negative.

The content of the new area may optionally be cleared with FillColor, if FillBack is true.

See Also

Color Types


Rotate

TCustomBitmap32.Rotate

procedure Rotate90(Dst: TBitmap32);

procedure Rotate180(Dst: TBitmap32);

procedure Rotate270(Dst: TBitmap32);

Description

A set of optimized routines for rotating the image 90, 180, and 270 degrees. Angles correspond to the clockwise rotation.

See Also

TCustomBitmap32


SaveToFile

TCustomBitmap32.SaveToFile

procedure SaveToFile(const FileName: string);

Description

Writes a bitmap image to disk. The image is saved as 32-bit BMP file.

If you need another pixel format or storage format, create intermediate TBitmap object or other TGraphic descendant, assign it from TBitmap32 and save it to a file.

See source of TBitmap.SaveToFile for more details.

See Also

LoadFromFile, SaveToStream


SaveToStream

TCustomBitmap32.SaveToStream

procedure SaveToStream(Stream: TStream);

Description

Stores a bitmap image to a stream. The data in the stream is stored in a form compatible with TBitmap, where each pixel allocates 32 bits.

[See also]: LoadFromStream, SaveToFile

See Also

LoadFromStream, SaveToFile


SetPixel

TCustomBitmap32.SetPixel

procedure SetPixelT(X, Y: Integer; Value: TColor32); overload;

procedure SetPixelT(var Ptr: PColor32; Value: TColor32); overload;

procedure SetPixelTS(X, Y: Integer; Value: TColor32);

procedure SetPixelX(X, Y: TFixed; Value: TColor32); deprecated;

procedure SetPixelXS(X, Y: TFixed; Value: TColor32); deprecated;

procedure SetPixelF(X, Y: Single; Value: TColor32); deprecated;

procedure SetPixelFS(X, Y: Single; Value: TColor32); deprecated;

Description

SetPixelT blends the pixel with a bitmap at specified coordinates using the specified color. The pixel’s alpha channel is used, but the coordinates are not validated.

The overloaded version of SetPixelT with a pixel pointer argument allows setting pixels addressed with the pointer rather than with coordinates. The pointer is automatically incremented to a next pixel position with each call to SetPixelT, for example:

var
P: PColor32;
I: Integer;
begin { Draw a fading white line from (10, 20) to (265, 20) }
P := PixelPtr[10, 20];
for I := 0 to 255 do SetPixelT(P, Color32(255, 255, 255, 255 - I));
end;

SetPixelTS is the SetPixelT method with added coordinate verification. If pixel coordinates lie outside the bitmap area, SetPixelTS does nothing.

SetPixelX/F/XS/FS methods are deprecated. Please use the PixelX/F/XS/FS property instead.

See Also

Naming Conventions, Pixel, Color Types, TFixed


SetSize

TCustomBitmap32.SetSize

function SetSize(NewWidth, NewHeight: Integer): Boolean; override;

procedure SetSize(Source: TPersistent); // implemented in TCustomMap

Description

Call SetSize to set a new width and height of the bitmap. If one of the arguments is zero, the bitmap is considered empty and in case of TBitmap32 its Handle property is set to zero.

Calling SetSize works faster than consecutive changing of Width and Height properties. If you use another bitmap or control as an argument, the bitmap will be sized to source dimensions.

If you have an external TCanvas attached, refresh it Handle property after resizing:

Bitmap32.SetSize(100, 200);

Canvas.Handle := Bitmap32.Handle;

After the SetSize call the image the bitmap should be completely redrawn.

See Also

TBitmap32.Handle, TCustomMap.Height, TBitmap32, TCustomMap, TCustomMap.Width


SetStipple

TCustomBitmap32.SetStipple

procedure SetStipple(NewStipple: TArrayOfColor32); overload;

procedure SetStipple(NewStipple: array of TColor32); overload;

Description

Sets a new stipple pattern.

See Also

GetStippleColor, Line Patterns, Color Types, Color Types


VertLine

TCustomBitmap32.VertLine

procedure VertLine(X, Y1, Y2: Integer; Value: TColor32);

procedure VertLineS(X, Y1, Y2: Integer; Value: TColor32);

procedure VertLineT(X, Y1, Y2: Integer; Value: TColor32);

procedure VertLineTS(X, Y1, Y2: Integer; Value: TColor32);

procedure VertLineTSP(X, Y1, Y2: Integer);

Description

Draws a vertical line from (X,Y1) to (X, Y2). The last point is included.

These functions works faster compared to Line. In versions with 'S' postfix necessary clipping to a bitmap coordinate range is provided. In versions without 'S', the Y2 value should be greater or equal to Y1.

VertLineTSP supports line patterns.

See Also

HorzLine, Line, Line Patterns, Naming Conventions, Color Types


Backend

TCustomBitmap32.Backend

property Backend: TBackend;

Description

Returns or sets the current back-end used for the bitmap's surface and additional graphics subsystem specific features that are accessible via interfaces.

Note: Interface queries on the current bitmap will also be delegated to the back-end.

See Also

Back-Ends, GR32_Backends, TBackend, TGDIBackend, TGDIMMFBackend, TMemoryBackend, TMMFBackend


Bits

TCustomBitmap32.Bits

property Bits: PColor32Array; // Read-only

type TColor32Array = array [0..0] of TColor32;

type PColor32Array = ^TColor32Array;

Description

The bits property contains the address of the first (top-left) pixel in a bitmap. If the bitmap is not allocated (width or height is zero), the returned address is nil.

Note, that numbering of rows in Graphics32 starts from the top-most one.

Data is continuously allocated in memory, row by row. You may safely access Width * Height elements, each of them is a 4-byte TColor32 value. For example:

var
  P: PColor32Array;
begin
  P := Bitmap32.Bits;
  for I := 0 to Bitmap32.Width * Bitmap32.Height - 1 do
    P[I] := Gray32(Random(255)); // fill with a random grayscale noise
end;

Note, that in this code no size verification is required, if width or height is zero, their product is zero and the loop will never be executed.

See Also

TCustomMap.Height, PixelPtr, ScanLine, Color Types, Color Types, TCustomMap.Width


Clipping

TCustomBitmap32.Clipping

property Clipping: Boolean;

Description

Determines if a clipping rect was set.


ClipRect

TCustomBitmap32.ClipRect

property ClipRect: TRect;

Description

Determines the clipping rectangle that all safe drawing operations are clipped to.

If no clipping rectangle is set, ClipRect is equal to the current dimension of the bitmap.

Note: Validation is performed upon setting of a clipping rect, so the clip rect is always sane.

See Also

Naming Conventions


CombineMode

TCustomBitmap32.CombineMode

property CombineMode: TCombineMode;

type TCombineMode = (cmBlend, cmMerge);

Description

TCombineMode defines how drawing operations on the bitmap combine the foreground color with the background.
It also determines how the bitmap is combined with the background of another bitmap when DrawMode is set to dmBlend.

  • cmBlend - Fast blending of foreground color with the background color using the supplied alpha. This method is not suited for working and preserving alpha-channels. Use this if you want to blend directly to the display buffer. Internally uses Blend and BlendEx routines.
  • cmMerge - Uses a completely different formula that also merges the alpha-channels. This mode is slower than blending but is suited for working with alpha-channels (eg. when composing in temporary buffers). Internally uses Merge and MergeEx routines.

See Also

Blend, BlendEx, Draw, DrawMode, DrawTo, Merge, MergeEx, TCombineMode


DrawMode

TCustomBitmap32.DrawMode

property DrawMode: TDrawMode;

type TDrawMode = (dmOpaque, dmBlend, dmCustom);

Description

Specifies how the bitmap should be combined with a background during pixel transfer and similar operations.

In dmOpaque mode, new pixels simply replace the background pixels. In dmBlend mode, they are combined using the alpha blending operation defined by CombineMode. This property is used while copying one bitmap into another, scaling, performing linear transformations etc. The dmCustom mode allows implementation of custom blending functions using the OnPixelCombine call-back event.

See Also

CombineMode, Draw, DrawTo, OnPixelCombine, TDrawMode


MasterAlpha

TCustomBitmap32.MasterAlpha

property MasterAlpha: TColor32;

Description

When blending a bitmap to the screen or to another bitmap, MasterAlpha normally controls the blending factor. The per-pixel opacity, stored in the blended bitmap, is premultiplied with MasterAlpha. If the MasterAlpha property is $00, the bitmap will be fully transparent, if it is equal to $FF, only per-pixel opacity, stored in bitmap’s alpha channel is used. This property is used only for bitmap blending, it does not affect pixel/line drawing and other similar routines.

When blending bitmaps in dmCustom draw mode, this property may be used for other purposes. Custom combining routine may use all 32 bits of MasterAlpha.

If the bitmap is in dmBlend draw mode and MasterAlpha is not in the [0…255] range, the blending result is not specified, it is your responsibility to keep MasterAlpha consistent with current draw mode.

See Also

DrawMode, Color Types


MeasuringMode

TCustomBitmap32.MeasuringMode

property MeasuringMode: Boolean; // readonly

Description

Determines if the bitmap is in measuring mode. In this mode drawing to the bitmap is only simulated. That is, drawing is actually omitted, but the OnAreaChanged event is still triggered.

For detailed description please refer to the additional topic dealing with repaint optimization.

See Also

Repaint Optimization, OnAreaChanged, Repaint Optimization


OuterColor

TCustomBitmap32.OuterColor

property OuterColor: TColor32;

Description

This property specifies the color returned by PixelS property when reading the pixel with coordinates that lie outside the bitmap. The default value is $00000000, which corresponds to a fully transparent black. It is also used when performing linear transformations of a bitmap.

See Also

Pixel, Color Types


PenColor

TCustomBitmap32.PenColor

property PenColor: TColor32;

Description

Simulates TCanvas.Pen.Color property. PenColor is used exclusively in MoveTo/LineTo functions.

See Also

LineTo, MoveTo, Color Types


Pixel

TCustomBitmap32.Pixel

property Pixel[X, Y: Integer]: TColor32; default;

property PixelS[X, Y: Integer]: TColor32;

property PixelW[X, Y: Integer]: TColor32;

property PixelX[X, Y: TFixed]: TColor32;

property PixelXS[X, Y: TFixed]: TColor32;

property PixelXW[X, Y: TFixed]: TColor32;

property PixelF[X, Y: Single]: TColor32;

property PixelFS[X, Y: Single]: TColor32;

property PixelFW[X, Y: Single]: TColor32;

Description

Pixel property sets the value of the pixel in the bitmap. Reading it, will return the color value of the pixel located at specified coordinates. This property does not validate the specified coordinates, so use it only then you are completely sure that you are not trying to read from or write to the outside of the bitmap boundary. Pixel is declared as default property, you may use it as shown below:

Bitmap32[10, 20] := Bitmap32[20, 10]; // copy a pixel from (20,10) to (10,20) position

PixelS is a 'safe' version of the Pixel property. When reading pixels from the outside the bitmap boundary, the value specified by OuterColor is returned. Writing with invalid coordinates will have no effect.

PixelW is the wrapping version of the Pixel property. When reading pixels from outside the bitmap boundary, the value returned is determined by the currently selected WrapMode. Thus always safe.

PixelX provides a method for accessing the pixels in fixed-point coordinates. The returned color is computed by performing linear interpolation on four adjacent pixels. Similarly, when pixels are set, they are antialiased.

PixelXS is a 'safe' version of the above property.

PixelXW is a wrapping version of the property PixelX.

PixelF is similar to PixelX but works with floating point coordinates instead of fixed point.

PixelFS is a 'safe' version of the above property.

PixelFW is a wrapping version of the above property.

See Also

Naming Conventions, OuterColor, SetPixel, Color Types, TFixed, WrapMode


PixelPtr

TCustomBitmap32.PixelPtr

property PixelPtr[X, Y: Integer]: PColor32; // read-only

Description

Converts coordinates of a pixel to its address in memory. Since TBitmap32 uses 32-bit DIBs, its memory is allocated as continuous string of 4-byte TColor32 values, starting at the top left corner.

Pixel with (0, 0) coordinates has the same address as specified in Bits property.

See Also

Bits, Pixel, ScanLine, Color Types, TCustomBitmap32


Resampler

TCustomBitmap32.Resampler

property Resampler: TCustomResampler;

Description

Resampler specifies the resampling method used for image stretching.

See Also

Draw, DrawTo, Sampling and Rasterization, TCustomResampler


ResamplerClassName

TCustomBitmap32.ResamplerClassName

property ResamplerClassName: string;

Description

ResamplerClassName determines which class to instantiate for Resampler.

See Also

Draw, DrawTo, Resampler, TCustomResampler


ScanLine

TCustomBitmap32.ScanLine

property ScanLine[Y: Integer]: PColor32Array; // read-only

Description

Provides indexed access to each line of pixels. Returns the same address as PixelPtr[0, Y]. This property acts similar to TBitmap.ScanLine.

See Also

Bits, PixelPtr, Color Types


StippleCounter

TCustomBitmap32.StippleCounter

property StippleCounter: Single;

Description

Use StippleCounter property to access current value of the stipple counter.

See Also

GetStippleColor, Line Patterns, OnPixelCombine, StippleStep


StippleStep

TCustomBitmap32.StippleStep

property StippleStep: Single;

Description

Provides access to stipple step. Default value is 1.0.

It is possible to set step to fractional or negative value.

See Also

GetStippleColor, Line Patterns, OnPixelCombine


StretchFilter

TCustomBitmap32.StretchFilter

property StretchFilter: TStretchFilter;

type TStretchFilter = (sfNearest, sfDraft, sfLinear, sfCosine, sfSpline, sfLanczos, sfMitchell);

Description

This property is deprecated as of version 1.8 of Graphics32. Please use Resampler and ResamplerClassName instead.

StretchFilter specifies color interpolation method for image stretching as well as for some other operations, like linear transformations. Some functions (transformations, for example) can interpolate only using the sfNearest and sfLinear filters, other values will be implicitly processed as sfLinear.

See Also

Draw, DrawTo, TStretchFilter


WrapMode

TCustomBitmap32.WrapMode

property WrapMode: TWrapMode;

type TWrapMode = (wmClamp, wmRepeat, wmMirror);

Description

Specifies how the wrapping Pixel property should behave.

See Also

Pixel, TWrapMode


OnAreaChanged

TCustomBitmap32.OnAreaChanged

property OnAreaChanged: TAreaChangedEvent;

Description

This event is triggered when a drawing operation changes an area on the bitmap. If the bitmap is in measuring mode, the actual drawing operation is omitted, but this event is still triggered.

See Also

Repaint Optimization, TAreaChangedEvent


OnPixelCombine

TCustomBitmap32.OnPixelCombine

property OnPixelCombine: TPixelCombineEvent;

type TPixelCombineEvent = procedure(F: TColor32; var B: TColor32; M: TColor32) of object;

Description

This event is called when the bitmap is drawn in dmCustom draw mode. Use this event to customize handling of colors. Note, however, that this event is called for every pixel, so keeping the event handler small and fast is in your own interest.

See Also

DrawMode, Examples, Color Types, TPixelCombineEvent


TCustomMap

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

Description

TCustomMap is a common ancestor for objects that hold 2D arrays of data.

Reference

Methods | Properties | Events
In TCustomMap:
Delete | Height | OnResize
Empty | Width |
Resized |  |
SetSize |  |
In TThreadPersistent:
Lock | LockCount |
Unlock |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
Create |  |
Destroy |  |
EndUpdate |  |


Delete

TCustomMap.Delete

procedure Delete; virtual;

Description

By default, Delete calls SetSize(0, 0). In descendants this is accompanied with deletion of stored data and freeing of the occupied memory.

See Also

SetSize


Empty

TCustomMap.Empty

function Empty: Boolean; virtual;

Description

Returns True if the data set is empty. Normally, it means that either its Width or Height is 0.

See Also

Height, Width


Resized

TCustomMap.Resized

procedure Resized; virtual;

Calls the OnResize event.

Descendants of TCustomMap call Resized internally after changing the size of the contained data array.

See Also

OnResize, TCustomMap


SetSize

TCustomMap.SetSize

procedure SetSize(NewWidth, NewHeight: Integer); virtual;

procedure SetSizeFrom(Source: TPersistent);

Description

Simultaneously changes both Width and Height of contained data.

The SetSizeFrom method 'knows' how to get the size from the following objects or their descendants: TCustomMap, TGraphic, TControl and nil. When other parameter is specified, TCusomMap will generate an exception.

The SetSize method is overriden in descendants (TBitmap32, TByteMap) so that bitmap bits are reallocated and byte map data array is resized.

See Also

Height, TBitmap32, TByteMap, TCustomMap, Width


Height

TCustomMap.Height

property Height: Integer;

Description

Specifies the height of the contained data array.

Use SetSize method to change both width and height simultaneously.

See Also

SetSize, Width


Width

TCustomMap.Width

property Width: Integer;

Description

Defines the width of the contained data array.

Writing into the Width property will resize the data array.

See Also

Height, SetSize


OnResize

TCustomMap.OnResize

property OnResize: TNotifyEvent;

Description

OnResize is called each time dimensions of the associated data array change. This event is normally preceeded with the OnChange call.

Similar to OnChange, generation of OnResize may be temporarily suppressed with BeginUpdate/EndUpdate.

See Also

TNotifiablePersistent.BeginUpdate, TNotifiablePersistent.EndUpdate, TNotifiablePersistent.OnChange


TCustomResampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

Description

TCustomResampler is a common ancestor for objects that resamples 2D arrays of data.

Reference

Methods | Properties | Events
In TCustomResampler:
Resample | Width |
In TCustomSampler:
FinalizeSampling |  |
GetSample |  |
GetSampleBounds |  |
HasBounds |  |
PrepareSampling |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
Create |  |
Destroy |  |
EndUpdate |  |

See Also

TBitmap32Resampler


Resample

TCustomResampler.Resample

procedure Resample(Dst: TBitmap32; DstRect: TRect; DstClip: TRect; Src: TBitmap32; SrcRect: TRect; CombineOp: TDrawMode; CombineCallBack: TPixelCombineEvent); virtual; abstract;

Description

Descendants must override this method in order to perform resampling of bitmaps.

See Also

Rectangle Types, TBitmap32, TBitmap32Resampler, TDrawMode, TPixelCombineEvent


Width

TCustomResampler.Width

property Width: Single;

Description

Returns the width of the associated kernel.


TCustomSampler

Hierarchy

TPersistent

|

TNotifiablePersistent

Description

TCustomSampler is a common ancestor for objects that can provide color samples.

Reference

Methods | Properties | Events
In TCustomSampler:
FinalizeSampling |  |
GetSample |  |
GetSampleBounds |  |
HasBounds |  |
PrepareSampling |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
Create |  |
Destroy |  |
EndUpdate |  |

See Also

Sampling and Rasterization


FinalizeSampling

TCustomSampler.FinalizeSampling

procedure FinalizeSampling; virtual;

Description

Descendants should override this method in order to perform special processing when sampling ends.

Note: FinalizeSampling is automatically called by TRasterizer when rasterization ends.

See Also

PrepareSampling, TRasterizer


GetSample

TCustomSampler.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

Prior to calling any GetSample method, PrepareSampling should be called, and finally FinalizeSampling should be called. Note that any number of calls to the GetSample methods can be made inside this Prepare/FinalizeSampling block.

See Also

Color Types, FinalizeSampling, PrepareSampling, TCustomSampler, TFixed


GetSampleBounds

TCustomSampler.GetSampleBounds

procedure GetSampleBounds: TRect; virtual; abstract;

Description

Descendants must override this method to define the area changed by the sampler, which is used for clipping purposes. If the sampler do not support returning a bounds rectangle, HasBounds should be set to false.

See Also

HasBounds, Rectangle Types


HasBounds

TCustomSampler.HasBounds

function HasBounds: Boolean; virtual;

Description

Descendants must set this to true, if sample bounds will be returned by GetSampleBounds.

See Also

GetSampleBounds


PrepareSampling

TCustomSampler.PrepareSampling

procedure PrepareSampling; virtual;

Description

Descendants should override this method in order to perform special preparations before the GetSample method is called.

Note: PrepareSampling is automatically called by TRasterizer before rasterization begins.

See Also

FinalizeSampling, GetSample, TRasterizer


TNotifiablePersistent

Hierarchy

TPersistent

Description

TNotifiablePersistent extends the standard TPersistent class with change notification events. That is, it provides methods and events allowing its descendants to issue notification on their changes. For example, TBitmap32 uses OnChange to notify its container (usually TImage32 or TBitmapLayer) that it was modified and its data has to be repainted to the screen. TNotifiablePersistent, however, does not use or implement automatic change notification itself. This is done in descendants.

Reference

Fields | Methods | Properties | Events
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Create |  |
 | Destroy |  |
 | EndUpdate |  |

See Also

TBitmap32, TBitmapLayer, TImage32


BeginUpdate

TNotifiablePersistent.BeginUpdate

procedure BeginUpdate;

Description

Call this method in order to temporarily disable the update notification.

BeginUpdate increases the UpdateCount property, which disables generation of OnChange events. Calls to BeginUpdate must be paired with EndUpdate and they may be safely nested.

See Also

EndUpdate, OnChange, UpdateCount


Changed

TNotifiablePersistent.Changed

procedure Changed;

Description

Calls the OnChange event, provided the change notification is not masked with BeginUpdate.

Descendants of TNotifiablePersistent call Changed after making changes to their data or properties.

You will need to call Changed explicitly in your application after leaving the BeginUpdate... EndUpdate block since EndUpdate itself does not internally call Changed.

See Also

EndUpdate, OnChange, TNotifiablePersistent


Create

TNotifiablePersistent.Create

constructor Create; virtual;

Description

Creates and initializes an instance of TNotifiablePersistent.

See Also

TNotifiablePersistent


Destroy

TNotifiablePersistent.Destroy

destructor Destroy; override;

Description

Destroys the TNotifiablePersistent object.

Do not call Destroy directly, use Free method instead.

See Also

TNotifiablePersistent


EndUpdate

TNotifiablePersistent.EndUpdate

procedure EndUpdate;

Description

Re-enables change notification previously disabled with BeginUpdate.

EndUpdate decreases the UpdateCount property and re-enables generation of OnChange events.

EndUpdate itself does not generate the OnChange event. You will need to call Changed explicitly, after calling EndUpdate in case the change notification is required.

See Also

BeginUpdate, Changed, OnChange, UpdateCount


UpdateCount

TNotifiablePersistent.UpdateCount

property UpdateCount: Integer; // Read-only; protected;

Description

The current nesting level of the update lock.

UpdateCount is increased each time you call the BeginUpdate method and is decreased with EndUpdate calls. The object does not generate OnChange as long as its UpdateCount is greater than 0.

See Also

BeginUpdate, EndUpdate, OnChange


OnChange

TNotifiablePersistent.OnChange

property OnChange: TNotifyEvent;

Description

OnChange is called immediately after the object changes. For example, TNotifiablePersistent's descendant TBitmap32, uses the OnChange event to notify its parent that something was changed in a bitmap, and the screen image must be updated.

Generation of OnChange events can be prevented by calling BeginUpdate.

See Also

BeginUpdate, Changed, TBitmap32, TNotifiablePersistent


TThreadPersistent

Hierarchy

TPersistent

|

TNotifiablePersistent

Description

TThreadPersistent extends the TNotifiablePersistent class with thread-safe locking.

The locking mechanism provides synchronization of simultaneous access to the same resource in applications with multiple threads and it works similar to the implementation found in TCanvas class. For additional information, see Delphi documentation on TCanvas.

Reference

Methods | Properties | Events
In TThreadPersistent:
Lock | LockCount |
Unlock |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
Create |  |
Destroy |  |
EndUpdate |  |

See Also

TNotifiablePersistent


Lock

TThreadPersistent.Lock

procedure Lock;

Description

Blocks other execution threads from locking the object until the Unlock method is called. If another thread tryes to call the Lock method of an object which is already locked, its execution will be stalled until the lock is released with Unlock method.

Once a thread has locked the object, it can make additional calls to Lock method without blocking its own execution. This prevents the thread from deadlocking itself while waiting for releasing of a lock that it already owns. LockCount is increased each time Lock is called.

See Also

LockCount, Unlock


Unlock

TThreadPersistent.Unlock

procedure Unlock;

Description

Removes the multithreading lock from the object.

Each call to Unlock decreases the LockCount property, allowing other threads to access the object when LockCount reaches 0. Each thread must call Unlock once for each time that it locked the object.

See Also

Lock, LockCount


LockCount

TThreadPersistent.LockCount

property LockCount: Integer; // Read-only; protected;

Description

LockCount represents the current nesting level of the threading lock. This is a counter shared by all running threads in the curent process.

The object is unlocked only when LockCount is 0 and only one thread can lock the object at the time. Call Lock to increase LockCount value and Unlock to decrease it.

See Also

Lock, Unlock


GR32_Backends

The GR32_Backends.pas unit contains definitions for all back-end interfaces required for TCustomBitmap32 and TBitmap32.

Contents

Interfaces
IBitmapContextSupport
ICanvasSupport
ICopyFromBitmapSupport
IDeviceContextSupport
IFontSupport
IPaintSupport
ITextSupport


IBitmapContextSupport

Description

IBitmapContextSupport provides means for accessing graphics subsystem specific information of the current back-end's surface.

Reference

Methods | Properties
In IBitmapContextSupport:
GetBitmapHandle | BitmapHandle
GetBitmapInfo | BitmapInfo


GetBitmapHandle

IBitmapContextSupport.GetBitmapHandle

function GetBitmapHandle: THandle;

Description

Getter method for the current bitmap handle. See BitmapHandle for details.

See Also

BitmapHandle


GetBitmapInfo

IBitmapContextSupport.GetBitmapInfo

function GetBitmapInfo: TBitmapInfo;

Description

Getter method for the current bitmap info structure. See BitmapInfo for details.

See Also

BitmapInfo


BitmapHandle

IBitmapContextSupport.BitmapHandle

property BitmapHandle: THandle read GetBitmapHandle;

Description

Returns the current bitmap handle for direct access via graphics sub system routines.

See Also

TBitmap32.BitmapHandle, GetBitmapHandle


BitmapInfo

IBitmapContextSupport.BitmapInfo

property BitmapInfo: TBitmapInfo read GetBitmapInfo;

Description

Returns the current bitmap info structure.

See Also

TBitmap32.BitmapInfo


ICanvasSupport

Description

ICanvasSupport exposes support for VCL's TCanvas.

Reference

Methods | Properties | Events
In ICanvasSupport:
CanvasAllocated | Canvas | OnCanvasChange
DeleteCanvas |  |
GetCanvas |  |
GetCanvasChange |  |
SetCanvasChange |  |


CanvasAllocated

ICanvasSupport.CanvasAllocated

function CanvasAllocated: Boolean;

Description

Determines if the canvas has already been allocated. Check the Canvas property for more details.

See Also

Canvas, TBitmap32.CanvasAllocated, TBitmap32.DeleteCanvas, DeleteCanvas


DeleteCanvas

ICanvasSupport.DeleteCanvas

procedure DeleteCanvas;

Description

DeleteCanvas explicitly frees the canvas instance in order to conserve resources. This method is called internally by TBitmap32.

See Also

TBitmap32.DeleteCanvas, TBitmap32


GetCanvas

ICanvasSupport.GetCanvas

function GetCanvas: TCanvas;

Description

Getter method for the current canvas instance. See Canvas and CanvasAllocated for more details.

See Also

Canvas, CanvasAllocated


GetCanvasChange

ICanvasSupport.GetCanvasChange

function GetCanvasChange: TNotifyEvent;

Description

Getter method for the current canvas change handler. See OnChanvasChange for more details.

See Also

OnCanvasChange


SetCanvasChange

ICanvasSupport.SetCanvasChange

procedure SetCanvasChange(Handler: TNotifyEvent);

Description

Setter method for the current canvas change handler. See OnChanvasChange for more details.

See Also

OnCanvasChange


Canvas

ICanvasSupport.Canvas

property Canvas: TCanvas read GetCanvas;

Description

Returns the current canvas instance.
A back-end may use lazy instantiation of the canvas - that is, it may create the canvas instance once the Canvas property is read for the first time.

See Also

TBitmap32.Canvas, Canvas, CanvasAllocated


OnCanvasChange

ICanvasSupport.OnCanvasChange

property OnCanvasChange: TNotifyEvent read GetCanvasChange write SetCanvasChange;

Description

This event is triggered when the canvas changes its internal state, e.g. when a new handle has been assigned. This event is used by TBitmap32.

See Also

TBitmap32.OnHandleChanged, TBitmap32


ICopyFromBitmapSupport

Description

ICopyFromBitmapSupport exposes support for copying from VCL's TBitmap instances. This interface is required to support assigning from TBitmap instances in the Assign method of TBitmap32.

Reference

Methods | Properties
In ICopyFromBitmapSupport:
CopyFromBitmap |

See Also

TBitmap32


CopyFromBitmap

ICopyFromBitmapSupport.CopyFromBitmap

procedure CopyFromBitmap(SrcBmp: TBitmap);

Description

Copies the SrcBmp into the current surface. The surface has been initialized beforehand by a call to ChangeSize or InitializeSurface.

See Also

TBackend.ChangeSize, ICopyFromBitmapSupport, TBackend.InitializeSurface


IDeviceContextSupport

Description

IDeviceContextSupport provides means for drawing to and from the current back-end's surface via a device context of the graphics subsystem.

Reference

Methods | Properties
In IDeviceContextSupport:
Draw | Handle
DrawTo |
GetHandle |


Draw

IDeviceContextSupport.Draw

procedure Draw(const DstRect, SrcRect: TRect; hSrc: HDC);

Description

Draws from another device context onto the current surface. Check TCustomBitmap32.Draw for details.

See Also

TCustomBitmap32.Draw


DrawTo

IDeviceContextSupport.DrawTo

procedure DrawTo(hDst: HDC; DstX, DstY: Integer); overload;

procedure DrawTo(hDst: HDC; const DstRect, SrcRect: TRect); overload;

Description

Draws the current surface onto another device context. Check TCustomBitmap32.DrawTo for details.

See Also

TCustomBitmap32.DrawTo


GetHandle

IDeviceContextSupport.GetHandle

function GetHandle: HDC;

Description

Getter method for the current device context handle. See Handle for details.

See Also

Handle


Handle

IDeviceContextSupport.Handle

property Handle: HDC read GetHandle;

Description

Returns the current device context handle of the back-end's surface for drawing by graphics sub system routines.

See Also

GetHandle, TBitmap32.Handle


IFontSupport

Description

IFontSupport provides access to font related settings and accompanies the ITextSupport interface in most cases.

Reference

Methods | Properties | Events
In IFontSupport:
GetFont | Font | OnFontChange
GetOnFontChange |  |
SetFont |  |
SetOnFontChange |  |
UpdateFont |  |

See Also

ITextSupport


GetFont

IFontSupport.GetFont

function GetFont: TFont;

Description

Getter method for the current font. See Font for more details.

See Also

Font


GetOnFontChange

IFontSupport.GetOnFontChange

function GetOnFontChange: TNotifyEvent;

Description

Getter method for the current font change handler. See OnFontChange for more details.

See Also

OnFontChange


SetFont

IFontSupport.SetFont

procedure SetFont(const Font: TFont);

Description

Setter method for the current font. See Font for more details.

See Also

Font


SetOnFontChange

IFontSupport.SetOnFontChange

procedure SetOnFontChange(Handler: TNotifyEvent);

Description

Setter method for the current font change handler. See OnFontChange for more details.

See Also

OnFontChange


UpdateFont

IFontSupport.UpdateFont

procedure UpdateFont;

Description

Updates the font in the current device context with the font specified by the Font property. Check TBitmap32.UpdateFont for more details.

See Also

Font, TBitmap32.UpdateFont


Font

IFontSupport.Font

property Font: TFont read GetFont write SetFont;

Description

Specifies a current font used by text output functions. Check TBitmap32.Font for details.

See Also

TBitmap32.Font


OnFontChange

IFontSupport.OnFontChange

property OnFontChange: TNotifyEvent read GetOnFontChange write SetOnFontChange;

Description

This event is triggered when the font changes its internal state, e.g. when a the font size changed. This event is used by TBitmap32.

See Also

TBitmap32


IPaintSupport

Description

IPaintSupport provides means for drawing the current back-end's surface onto the screen.

Reference

Methods
In IPaintSupport:
CheckPixmap
DoPaint
ImageNeeded


CheckPixmap

IPaintSupport.CheckPixmap

procedure CheckPixmap;

Description

Converts the current surface to a compatible representation for the graphics sub system. Some graphics sub system such as Qt require this in order to draw on the surface using the QPainter class.


DoPaint

IPaintSupport.DoPaint

procedure DoPaint(ABuffer: TBitmap32; AInvalidRects: TRectList; ACanvas: TCanvas; APaintBox: TCustomPaintBox32);

Description

Draws the buffer specified by ABuffer (the back-end's surface) onto the canvas ACanvas owned by the paintbox APaintBox.

AInvalidRects specifies a list of rects that require repainting. If the list is empty this method draws the buffer ABuffer into the ViewportRect of the paintbox APaintBox.

See Also

TCustomPaintBox32.GetViewportRect, TBitmap32, TCustomPaintBox32, TRectList


ImageNeeded

IPaintSupport.ImageNeeded

procedure ImageNeeded;

Description

Converts the compatible representation of the graphics sub system back to the surface.

See Also

CheckPixmap


ITextSupport

Description

ITextSupport provides support for drawing text onto the surface and measuring the extent of a given text. Implementing IFontSupport is mandatory.

Reference

Methods | Properties
In ITextSupport:
TextExtent |

See Also

IFontSupport


TextExtent

ITextSupport.TextExtent

function TextExtent(const Text: String): TSize;

function TextExtentW(const Text: Widestring): TSize;

Description

Unicode and ANSI versions of the text measuring methods. Please refer to TBitmap32.TextExtent for a more detailed description.

See Also

TBitmap32.TextExtent


GR32_Backends_Generic

The GR32_Backends_Generic.pas unit contains generic back-ends that are mostly independent of the operating system's graphics subsystem.

Contents

Classes
TMemoryBackend
TMMFBackend


TMemoryBackend

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TBackend

Description

This back-end allocates the memory required for the surface directly in RAM. On Windows / VCL it does not acquire any GDI handles or resources.

It does not support any of the interfaces required for TBitmap32, making it lightweight but also feature limited. Temporarily switching to a more sophisticated back-end like TGDIBackend can alleviate this problem.

TMemoryBackend is the default back-end of TCustomBitmap32.

Reference

Fields | Methods | Properties | Events
In TBackend:
 | Assign | Bits | OnChanging
 | ChangeSize |  |
 | Changing |  |
 | Clear |  |
 | Create |  |
 | Destroy |  |
 | Empty |  |
 | FinalizeSurface |  |
 | InitializeSurface |  |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

GR32_Backends, TBitmap32, TCustomBitmap32, TGDIBackend


TMMFBackend

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TBackend

|

TMemoryBackend

Description

This back-end is similar to TMemoryBackend in that it does not use any GDI handles and is lightweight. However, the memory backing the surface is not allocated in RAM but in so called memory-mapped files. A memory-mapped file is a segment of virtual memory which has been assigned a direct byte-for-byte correlation with some portion of a (temporary) file or swap file for that matter.

This approach may allow allocating large bitmaps that would otherwise not be allocateable by the default memory manager. The drawback is reduced performance due to swapping to and from disk that may occur.

Reference

Methods | Properties | Events
In TMMFBackend:
Create |  |
In TBackend:
Assign | Bits | OnChanging
ChangeSize |  |
Changing |  |
Clear |  |
Destroy |  |
Empty |  |
FinalizeSurface |  |
InitializeSurface |  |
In TThreadPersistent:
Lock | LockCount |
Unlock |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
EndUpdate |  |

See Also

TMemoryBackend


Create

TMMFBackend.Create

constructor Create(Owner: TCustomBitmap32; IsTemporary: Boolean = True; const MapFileName: string = ''); virtual;

Description

Creates and initializes an instance of TMMFBackend.

If Owner is specified the new back-end instance is automatically assigned to the TCustomBitmap32 instance. The existing back-end of the bitmap instance will be replaced and surface data is transfered to the new back-end instance via the Assign method.

IsTemporary defines whether the allocated file should only be used for the life-cycle of the surface.

MapFileName defines the filename of the file that should created or re-used as memory-mapped file. Passing an empty string as MapFileName will result in using a part of the swap file for the surface.

Setting IsTemporary to false while defining a MapFileName will result in a permanent file being created that can be re-used.

For an usage example of the constructor please refer to the additional topic Back-ends in this documentation.

See Also

TBackend.Assign, Back-Ends, TCustomBitmap32, TGDIMMFBackend, TMMFBackend


GR32_Backends_VCL

The GR32_Backends_VCL.pas unit contains back-ends that rely on the VCL and the GDI graphics subsystem.

Contents

Classes
TGDIBackend
TGDIMemoryBackend
TGDIMMFBackend


TGDIBackend

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TBackend

Description

This back-end allocates the memory and resources required for the surface directly via the Windows GDI subsystem.

Features

  • Access to the surface via GDI routines (via IDeviceContextSupport and IBitmapContextSupport);
  • Access to the surface via the default VCL canvas (via ICanvasSupport);
  • Support for text drawing and measuring and related font methods (via ITextSupport and IFontSupport);
  • Supports all of the other interfaces required for TBitmap32, making it the default back-end for this class.

Reference

Fields | Methods | Properties | Events
In TBackend:
 | Assign | Bits | OnChanging
 | ChangeSize |  |
 | Changing |  |
 | Clear |  |
 | Create |  |
 | Destroy |  |
 | Empty |  |
 | FinalizeSurface |  |
 | InitializeSurface |  |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

GR32_Backends, IBitmapContextSupport, ICanvasSupport, IDeviceContextSupport, IFontSupport, ITextSupport, TBitmap32


TGDIMemoryBackend

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TBackend

Description

This backend keeps the backing buffer entirely in memory and offers IPaintSupport without allocating a GDI handle

Features

  • Access to the surface via GDI routines (via IDeviceContextSupport);
  • Supports painting via IPaintSupport

Reference

Fields | Methods | Properties | Events
In TBackend:
 | Assign | Bits | OnChanging
 | ChangeSize |  |
 | Changing |  |
 | Clear |  |
 | Create |  |
 | Destroy |  |
 | Empty |  |
 | FinalizeSurface |  |
 | InitializeSurface |  |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

IDeviceContextSupport, IPaintSupport


TGDIMMFBackend

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TBackend

|

TGDIBackend

Description

This back-end behaves like TGDIBackend in what features it supports. However it is different from TGDIBackend in the way the memory for the surface is allocated: Instead of allocating in RAM the memory backing the surface is allocated in so called memory-mapped files. A memory-mapped file is a segment of virtual memory which has been assigned a direct byte-for-byte correlation with some portion of a (temporary) file or swap file for that matter.

This approach may allow allocating large bitmaps that would otherwise not be allocateable by the GDI subsystem. The drawback is reduced performance due to swapping to and from disk that may occur.

Reference

Methods | Properties | Events
In TGDIMMFBackend:
Create |  |
In TBackend:
Assign | Bits | OnChanging
ChangeSize |  |
Changing |  |
Clear |  |
Destroy |  |
Empty |  |
FinalizeSurface |  |
InitializeSurface |  |
In TThreadPersistent:
Lock | LockCount |
Unlock |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
EndUpdate |  |

See Also

TGDIBackend


Create

TGDIMMFBackend.Create

constructor Create(Owner: TCustomBitmap32; IsTemporary: Boolean = True; const MapFileName: string = ''); virtual;

Description

Creates and initializes an instance of TGDIMMFBackend.

If Owner is specified the new back-end instance is automatically assigned to the TCustomBitmap32 instance. The existing back-end of the bitmap instance will be replaced and surface data is transfered to the new back-end instance via the Assign method.

IsTemporary defines whether the allocated file should only be used for the life-cycle of the surface.

MapFileName defines the filename of the file that should created or re-used as memory-mapped file. Passing an empty string as MapFileName will result in using a part of the swap file for the surface.

Setting IsTemporary to false while defining a MapFileName will result in a permanent file being created that can be re-used.

For an usage example of the constructor please refer to the additional topic Back-ends in this documentation.

See Also

TBackend.Assign, Back-Ends, TCustomBitmap32, TGDIMMFBackend


GR32_Blend

GR32_Blend.pas includes low-level functions, mostly blending of pixels. The library automatically determines whether the CPU supports MMX instructions, and uses MMX optimized routines when it is possible.

Contents

Types | Routines | Variables
TBlendLine | Blend | MMX_ACTIVE
TBlendLineEx | BlendEx |
TBlendMem | BlendLine |
TBlendMemEx | BlendLineEx |
TBlendReg | ColorAdd |
TBlendRegEx | ColorAverage |
TCombineMem | ColorDifference |
TCombineReg | ColorDiv |
 | ColorExclusion |
 | ColorMax |
 | ColorMin |
 | ColorModulate |
 | ColorScale |
 | ColorSub |
 | Combine |
 | EMMS |
 | Lighten |
 | Merge |
 | MergeEx |


TBlendLine

type TBlendLine = procedure (Src, Dst: PColor32; Count: Integer);

Desctiption

TBlendline is a type for line blending procedures. It is mainly used internally for handling specific CPU feature optimized versions (MMX etc.). See source code for details.

See Also

BlendLine, Color Types


TBlendLineEx

type TBlendLineEx = procedure (Src, Dst: PColor32; Count: Integer; M: TColor32);

Desctiption

TBlendline is a type for line blending procedures with additional master alpha parameter. It is mainly used internally for handling specific CPU feature optimized versions (MMX etc.). See source code for details.

See Also

BlendLineEx


TBlendMem

type TBlendMem = procedure (F: TColor32; var B: TColor32);

Desctiption

TBlendMem is a type for blending procedures. It is mainly used internally for handling specific CPU feature optimized versions (MMX etc.). See source code for details.

See Also

Blend, Color Types


TBlendMemEx

type TBlendMemEx = procedure (F: TColor32; var B: TColor32; M: TColor32);

Desctiption

TBlendMemEx is a type for blending procedures. It is mainly used internally for handling specific CPU feature optimized versions (MMX etc.). See source code for details.

See Also

BlendEx, Color Types


TBlendReg

type TBlendReg = function (F, B: TColor32): TColor32;

Desctiption

TBlendReg is a type for blending procedures. It is mainly used internally for handling specific CPU feature optimized versions (MMX etc.). See source code for details.

See Also

Blend, Color Types


TBlendRegEx

type TBlendRegEx = function (F, B, M: TColor32): TColor32;

Desctiption

TBlendRegEx is a type for blending procedures. It is mainly used internally for handling specific CPU feature optimized versions (MMX etc.). See source code for details.

See Also

BlendEx, Color Types


TCombineMem

type TCombineMem = procedure (F: TColor32; var B: TColor32; W: TColor32);

Desctiption

TCombineMem is a type for combining procedures. It is mainly used internally for handling specific CPU feature optimized versions (MMX etc.). See source code for details.

See Also

Combine


TCombineReg

type TCombineReg = function (X, Y, W: TColor32): TColor32;

Desctiption

TCombineReg is a type for color combining procedures. It is mainly used internally for handling specific CPU feature optimized versions (MMX etc.). See source code for details.

See Also

Color Types, Combine


Blend

function BlendReg(F, B: TColor32): TColor32;

procedure BlendMem(F: TColor32; var B: TColor32);

Description

Mixes a foregrownd (F) color with the background color (B) using the alpha component of the foreground color.

SRGB = FA * FRGB + (1 – FA) * BRGB;

BlendReg takes parameters and produces the result operating on CPU registers.

BlendMem operates with the background color referenced by a memory address.

Using BlendMem is more efficient when blending/combining data to a bitmap, since it excludes writing operation for transparent pixels and reading operation for opaque ones.

Note, that after using the Blend function, you have to call EMMS. Otherwise CPU will be unable to handle floating point instructions.

See Also

BlendEx, Combine, EMMS, Merge, MergeEx, Color Types


BlendEx

function BlendRegEx(F, B, M: TColor32): TColor32;

procedure BlendMemEx(F: TColor32; var B: TColor32; M: TColor32);

Description

Mixes a foreground color with the background color using alpha of the foreground color scaled by the master alpha value M.

SRGB = (M * FA) * FRGB + (1 – (M * FA)) * BRGB;

M is defined as TColor32 to avoid unnecessary type conversions, it must store only values in [0..255] range, the function does not perform range checking and the result in case M > 255 is not specified.

BlendRegEx takes parameters and produces the result operating on CPU registers.

BlendMemEx operates with the background color referenced by a memory address.

Using BlendMemEx is more efficient when blending/combining data to a bitmap since it excludes writing operation for transparent pixels and reading operation for opaque ones.

Note, that after using BlendEx functions, you have to call EMMS. Otherwise CPU will be unable to handle floating point instructions.

See Also

Blend, Combine, EMMS, Merge, MergeEx, Color Types


BlendLine

procedure BlendLine(Src, Dst: PColor32; Count: Integer);

Description

An optimized row processing version of Blend.

See Also

Blend, BlendLineEx, Color Types


BlendLineEx

procedure (Src, Dst: PColor32; Count: Integer; M: TColor32);

Description

An optimized row processing version of BlendEx.

See Also

BlendEx, BlendLine, Color Types


ColorAdd

function ColorAdd(C1, C2: TColor32): TColor32;

Description

Returns the sum of two colors. Each color component: red, green, blue and alpha is added separately and summation results are clamped to fit into [0…255] range.

See Also

ColorSub, Color Types


ColorAverage

function ColorAverage(C1, C2: TColor32): TColor32;

Description

Compute the average color of C1 and C2.

See Also

ColorAdd, Color Types


ColorDifference

function ColorDifference(C1, C2: TColor32): TColor32;

Description

Compute the absolute difference between C1 and C2. The resulting color components are clamped to the [0…255] range.

See Also

ColorSub, Color Types


ColorDiv

function ColorDiv(C1, C2: TColor32): TColor32;

Description

The resulting color components are the result of the division of corresponding components from C2 and C1.

See Also

Color Types


ColorExclusion

function ColorExclusion(C1, C2: TColor32): TColor32;

Description

The resulting color components are formed from the formula

S = C1 + C2 - 2 * C1 * C2.

See Also

ColorDifference, Color Types


ColorMax

function ColorMax(C1, C2: TColor32): TColor32;

Description

Resultin color components are maximums of corresponding components in C1 and C2.

See Also

ColorMin, Color Types


ColorMin

function ColorMin(C1, C2: TColor32): TColor32;

Description

Resultin color components are minimums of corresponding components in C1 and C2.

See Also

ColorMax, Color Types


ColorModulate

function ColorModulate(C1, C2: TColor32): TColor32;

Description

The resulting color components are calculated as products of corresponding components in C1 and C2 divided by $FF:

See Also

Color Types


ColorScale

function ColorScale(C, W: TColor32): TColor32;

Description

The resulting color S is formed by scaling the individual components of C by a factor W. The result is clamped to the [0…255] range.

SARGB = CARGB * W.

See Also

ColorModulate, Color Types


ColorSub

function ColorSub(C1, C2: TColor32): TColor32;

Description

Subtracts C2 from C1. The resulting color components are clamped to [0…255] range. The alpha channel is subtracted as well.

See Also

ColorAdd, Color Types


Combine

function CombineReg(X, Y, W: TColor32): TColor32;

procedure CombineMem(F: TColor32; var B: TColor32; W: TColor32);

Description

Returns the color with components calculated as linear interpolation between X and Y colors. The W parameter, which sholuld be in [0..255] range, specifies the weight of the first color (X). The alpha channel is interpolated as well.

SRGBA = W * XRGBA + (1 – W) * YRGBA;

CombineReg takes parameters and produces the result operating on CPU registers.

CombineMem operates with the background color referenced by a memory address.

Using CombineMem is more efficient when blending/combining data to a bitmap since it excludes writing operation for transparent pixels and reading operation for opaque ones.

Note, that after using Combine functions, you have to call EMMS. Otherwise CPU will be unable to handle floating point instructions.

See Also

Blend, BlendEx, EMMS, Color Types


EMMS

procedure EMMS;

Description

Calls to blending functions must be followed by EMMS procedure. This restores the state of FPU flags, altered by MMX instructions. When CPU does not support MMX or SSE2 is available, the EMMS function does nothing.

This function must be called after Blend, BlendEx or Combine calls, otherwise CPU will not be able to execute floating point instructions.

If you are using color algebra (such as ColorAdd, ColorMax etc.) that use MMX internally you also have to make sure that EMMS is called.

In case SSE2 is available this function becomes a stub with the smallest possible impact on performance. However, for backward compatibility it is mandatory to always keep a call to this procedure in the code.

A typical example of using blending functions:

try
for i := X1 to X2 do
begin
BlendMem(Clr32, P^); // This function uses MMX
Inc(P);
end;
finally
EMMS; // EMMS is called only once, since there is no FPU code inside the loop
end;

See Also

Blend, BlendEx, ColorAdd, ColorMax, Combine


Lighten

function Lighten(C: TColor32; Amount: Integer): TColor32;

Description

The resulting color is formed from the color components of the parameter C by adding Amount to each of them and clipping the sum to [0…255] range.

Amount may be negative.

See Also

Color Types


Merge

function MergeReg(F, B: TColor32): TColor32;

procedure MergeMem(F: TColor32; var B: TColor32);

Description

Merges a foregrownd (F) color with the background color (B) using the alpha component of the foreground color. It does merge the alpha-channels.

SA = 1 - (1 - FA) (1 - BA)

SRGB = (FA * FRGB + BA * (1 - FA) * BRGB) / SA

MergeReg takes parameters and produces the result operating on CPU registers.

MergeMem operates with the background color referenced by a memory address.

Note, that after using the Merge function, you have to call EMMS. Otherwise CPU will be unable to handle floating point instructions.

See Also

Blend, BlendEx, Combine, EMMS, MergeEx, Color Types


MergeEx

function MergeRegEx(F, B, M: TColor32): TColor32;

procedure MergeMemEx(F: TColor32; var B: TColor32; M: TColor32);

Description

Merges the foreground color with the background color using alpha of the foreground color scaled by the master alpha value M. Alpha-Channels are also merged.

SA = 1 - (1 - (M * FA)) (1 - BA)

SRGB = ((M * FA) * FRGB + BA * (1 - FA) * BRGB) / SA

M is defined as TColor32 to avoid unnecessary type conversions, it must store only values in [0..255] range, the function does not perform range checking and the result in case M > 255 is not specified.

MergeRegEx takes parameters and produces the result operating on CPU registers.

MergeMemEx operates with the background color referenced by a memory address.

Note, that after using MergeEx functions, you have to call EMMS. Otherwise CPU will be unable to handle floating point instructions.

See Also

Blend, BlendEx, Combine, EMMS, Merge, Color Types


MMX_ACTIVE

var MMX_ACTIVE: Boolean;

Description

This variable indicates if the CPU supports MMX instructions. MMX_ACTIVE is initialized automatically upon the library initialization.


GR32_Containers

GR32_Containers.pas includes a number of auxiliary container classes.

Contents

Classes
TClassList
TPointerMap
TPointerMapIterator
TRectList


TClassList

Hierarchy

TList

Description

TClassList is a container class for storing class types in list form. Handling is similar to TList, but instead of storing pointers it stores class types. Please refer to the TList documentation for details.

We'll cover the additional methods for this class.

Reference

Methods
In TClassList:
Find
GetClassNames


Find

TClassList.Find

function Find(AClassName: string): TClass;

Description

Searches the list for a specific class name. If no match is found, this function method will return nil.


GetClassNames

TClassList.GetClassNames

procedure GetClassNames(Strings: TStrings);

Description

Adds names of all classes currently in the list to the string list provided by the parameter Strings.


TPointerMap

Hierarchy

TObject

Description

TPointerMap implements a simple pointer to pointer map. It uses a hash-like structure internally, thus, data lookup is very fast compared to an iterative approach - especially if you have many entries in the map. However, it is also more limited than a list approach since it does not support index based operation. If you need to iterate through a pointer map please refer to TPointerMapIterator.

Reference

Methods | Properties
In TPointerMap:
Add | Count
Clear | Data
Contains |
Find |
Remove |

See Also

TPointerMapIterator


Add

TPointerMap.Add

function Add(NewItem: PItem): PPData; overload;

function Add(NewItem: PItem; out IsNew: Boolean): PPData; overload;

function Add(NewItem: PItem; NewData: PData): PPData; overload;

function Add(NewItem: PItem; NewData: PData; out IsNew: Boolean): PPData; overload;

Description

Adds a new item to the pointer map. The function method will return a pointer to the data PPData.

NewItem specifies the pointer of the new item;

NewData specified the pointer of the data associated with the new item;

IsNew returns whether the item was added to the list or if an existing copy was modified.


Clear

TPointerMap.Clear

procedure Clear;

Description

Clears all entries from the pointer map.


Contains

TPointerMap.Contains

function Contains(Item: PItem): Boolean;

Description

Returns whether an entry exists in the pointer map.


Find

TPointerMap.Find

function Find(Item: PItem; out Data: PPData): Boolean;

Description

Returns whether an entry Item exists in the pointer map. If it exists, the Data pointer is returned by Data.


Remove

TPointerMap.Remove

function Remove(Item: PItem): PData;

Description

Remove the entry specified by Item from the pointer map and returns its Data.


Count

TPointerMap.Count

property Count: Integer;

Description

Returns the amount of entries in the pointer map.


Data

TPointerMap.Data

property Data[Item: PItem]: PData; default;

Description

Returns or sets the associated data for an entry Item. If the entry does not exist in the map, an exception of type EListError will be raised.
The data lookup is fast because it uses a hash-like structure internally.


TPointerMapIterator

Hierarchy

TObject

Description

TPointerMapIterator is an auxiliary class for iterating through pointer maps - an operation not directly supported by TPointerMap.

The iterator should be used in the following fashion:

with TPointerMapIterator.Create(MyPointerMap) do
try
  while Next do
  begin
    // do something with Item and Data here...
  end;
finally
  Free;
end;

Reference

Methods | Properties
In TPointerMapIterator:
Next | Data
 | Item


Next

TPointerMapIterator.Next

function Next: Boolean;

Description

Retrieves the next entry in the pointer map and saves a copy to the Data and Item property. Returns True if the operation succeeded, False if there is no more entry to fetch.

See Also

Data, Item


Data

TPointerMapIterator.Data

property Data: PData;

Description

Returns the associated Data entry of current entry Item of the iterator.

See Also

Item


Item

TPointerMapIterator.Item

property Item: PItem;

Description

Returns the current entry Item of the iterator.


TRectList

Hierarchy

TObject

Description

TRectList is a container class for storing rectangles. Handling is similar to TList, but instead of storing pointers it stores TRect. Please refer to the TList documentation for further details.

Internally the rectangles are saved in an array structure instead of a pointer based approach, so as to have a more memory efficient storage.


GR32_ExtImage

GR32_ExtImage.pas is an extension to the GR32 image unit. It provides a set of useful classes and routines for threaded rasterization and rendering.

Contents

Types | Classes | Routines
TRenderMode | TRenderThread | Rasterize
 | TSyntheticImage |

See Also

GR32_Image


TRenderMode

type TRenderMode = (rnmFull, rnmConstrained);

Description

TRenderMode defines how the synthetic image will render or rasterize.

  • rnmFull – a color information from the foreground image completely replaces the background data;
  • rnmConstrained – foreground and background colors are blended together using per-pixel opacity of the foreground bitmap (stored in its alpha channel), multiplied by its MasterAlpha;

See Also

TCustomBitmap32.MasterAlpha


Rasterize

procedure Rasterize(Rasterizer: TRasterizer; Bitmap: TBitmap32; DstRect: TRect);

Description

Rasterize is a simple TRenderThread based rasterize auxiliary routine. Calling Rasterize will start up a seperate rasterization thread and rasterize through that with the provided Rasterizer.

See Also

Rectangle Types, TBitmap32, TRasterizer, TRenderThread


TRenderThread

Hierarchy

TPersistent

Description

TRenderThread extends the standard TPersistent class with the thread-safe locking and declares change notification events.

The locking provides means of syncronization of simultaneous access to the same resource in applications with multiple threads and it works similar to that in TCanvas class. For additional information, see Delphi documentation on TCanvas.

This class also declares change notification abilities. That is, it provides methods and events allowing it descendants to issue notification on their changes. For example, TBitmap32 uses OnChange to notify its container (usually TImage32 or TBitmapLayer) that it was modified and its data has to be repainted to the screen. TThreadPersistent, however, does not use or implement automatic change notification itself. This is done in descendants.

Reference

Fields | Methods | Properties
In TRenderThread:
 | Create |

See Also

TNotifiablePersistent.OnChange, TBitmap32, TBitmapLayer, TImage32


Create

TRenderThread.Create

constructor Create(Rasterizer: TRasterizer; Bitmap: TBitmap32; DstRect: TRect; Suspended: Boolean);

Description

Creates an instance of TRenderThread. If Suspended then the rasterization process will not be started, otherwise the threaded rasterization will start immediatly.

See Also

Rectangle Types, TBitmap32, TRasterizer, TRenderThread


TSyntheticImage

Hierarchy

TCustomControl

|

TCustomPaintBox32

|

TPaintBox32

Description

TSyntheticImage32 implements the generic behavior introduced in TCustomPaintBox32. It publishes some inherited properties from its ancestors and, in addition, it calls the OnPaintBuffer event when the buffer needs to be repainted.

Reference

Methods | Properties | Events
In TSyntheticImage:
Rasterize | AutoRasterize |
 | BitmapAlign |
 | Buffer |
 | DstRect |
 | Rasterizer |
 | RenderMode |
In TPaintBox32:
Create |  | OnPaintBuffer
DoPaintBuffer |  |
Flush |  |
In TCustomPaintBox32:
Destroy | BufferOversize | OnMouseEnter
ForceFullInvalidate | BufferValid | OnMouseLeave
GetViewportRect | Options |
Invalidate | RepaintMode |
Loaded |  |
Resize |  |
SetBounds |  |

See Also

TCustomPaintBox32


Rasterize

TSyntheticImage.Rasterize

procedure Rasterize;

Description

Rasterize starts the rasterization process.


AutoRasterize

TSyntheticImage.AutoRasterize

property AutoRasterize: Boolean;

Description

If AutoRasterize then the synthetic image will rasterize when the associated rasterizer has changed, otherwise Rasterize has to be called in order to start rasterization. AutoRasterize is set true upon creation.

See Also

Rasterize, Rasterizer


BitmapAlign

TSyntheticImage.BitmapAlign

property BitmapAlign: TBitmapAlign;

type TBitmapAlign = (baTopLeft, baCenter, baTile, baCustom);

Description

Specifies how the buffer bitmap is located withing the control's boundaries.


Buffer

TSyntheticImage.Buffer

property Buffer: TBitmap32; // Read only;

Description

Provides direct access to the back buffer.

See Also

TBitmap32


DstRect

TSyntheticImage.DstRect

property DstRect: TRect;

Description

DstRect specifies the rasterization boundaries when render mode is rnmConstrained.

See Also

Rectangle Types, RenderMode


Rasterizer

TSyntheticImage.Rasterizer

property Rasterizer: TRasterizer;

Description

This property specifies which rasterizer is used to render to the synthetic image control.

See Also

TRasterizer


RenderMode

TSyntheticImage.RenderMode

property RenderMode: TRenderMode;

Description

Specifies whether the complete control is updated or only the area specified by the DstRect property.

See Also

DstRect, TRenderMode


GR32_Filters

GR32_Filters.pas provides some basic functions for operating over bitmap data.

Contents

Types | Routines
TLogicalOperator | AlphaToGrayscale
TLUT8 | ApplyBitmask
 | ApplyLUT
 | ChromaKey
 | ColorToGrayScale
 | CopyComponents
 | CreateBitmask
 | IntensityToAlpha
 | Invert
 | InvertRGB


TLogicalOperator

type TLogicalOperator = (loXOR, loAND, loOR);

Description

An enumerated type that specifies logical (bitwise) operators for use in ApplyBitmask.

See Also

ApplyBitmask


TLUT8

type TLUT8 = array [Byte] of Byte;

Description

A look-up table of 256 values, each ranging from 0 to 255.

TLUT8 is used to transform color data with ApplyLUT procedure.

See Also

ApplyLUT


AlphaToGrayscale

procedure AlphaToGrayscale(Dst, Src: TCustomBitmap32);

Description

This function transforms an alpha channel from Src bitmap into grayscale (R=A, G=A, B=A) color in Dst bitmap. If necessary, Dst bitmap is resized to fit Src dimesions.

It writes only RGB components into Dst. The alpha channel (A) remains intact, provided that dimensions of Dst and Src match before AlphaToGrayScale call.

This function is useful when it is necessary to visualize the alpha channel, or when you want to store it as standard bitmap into a file.

See Also

IntensityToAlpha, TCustomBitmap32


ApplyBitmask

procedure ApplyBitmask(
Dst: TCustomBitmap32;
DstX: Integer;
DstY: Integer;
Src: TCustomBitmap32;
SrcRect: TRect;
Bitmask: TColor32;
LogicalOperator: TLogicalOperator;
);

procedure ApplyBitmask(
ABitmap: TCustomBitmap32;
ARect: TRect;
Bitmask: TColor32;
LogicalOperator: TLogicalOperator;
);

Description

ApplyBitmask performs a logical (bitwise) operation on a bitmap fragment specified by SrcRect into location (DstX, DstY) or directly in-place on ABitmap. The operation is carried out in the following manner: "Source Pixel [Logical Operation] Bitmask" regardless of present destination or in-place operation. The logical operation is defined by the provided Logical Operator.

Each byte in the bitmask will be used as component corresponding operand. The following combinations illustrates different applications:

Description | Parameter Values | Source | Result
Zero out Red and Blue components, leave the rest untouched | LogicalOperator = loAND Bitmask = $FF00FF00 |  |
Invertion of Blue component, leave the rest untouched | LogicalOperator = loXOR Bitmask = $000000FF |  |
Full power to Red component, leave the rest untouched | LogicalOperator = loOR Bitmask = $00FF0000 |  |
Weird filter | LogicalOperator = loOR Bitmask = $BABEC0DE |  |

As seen above, the bitmask does not necessarily have to contain 0 or $FF in each component segment - intermediate values can also be used however with limited realistic applications (read: weird filters).
You may use auxiliary function CreateBitmask to create bitmasks.

See Also

Color Types, CopyComponents, CreateBitmask, Invert, TCustomBitmap32, TLogicalOperator, Rectangle Types


ApplyLUT

procedure ApplyLUT(Dst, Src: TCustomBitmap32; const LUT: TLUT8; PreserveAlpha: Boolean = False);

Description

Converts color from Src to Dst using a look-up table (LUT parameter) to map the color components. The alpha channel of the result is set to $FF by default. However, you can override this behaviour by setting PreserveAlpha to True.

RDST = LUT[RSRC];

GDST = LUT[GSRC];

BDST = LUT[BSRC];

If PreserveAlpha then ADST = ASRC else ADST = $FF;

This function supports in-place operation, that is Dst may be the same as Src.

See Also

TCustomBitmap32, TLUT8


ChromaKey

procedure ChromaKey(ABitmap: TCustomBitmap32; TrColor: TColor32);

Description

Preprocesses a Bitmap for standard color key transparency, ie. areas that are of color TrColor are made transparent.

It is possible to use this function several times for different colors.

See Also

Color Types, TCustomBitmap32


ColorToGrayScale

procedure ColorToGrayscale(Dst, Src: TCustomBitmap32; PreserveAlpha: Boolean = False);

Description

Calculates color intensity from Src and writes it as a grayscale image into Dst. The alpha channel in Dst will be set to $FF by default. However, you can override this behaviour by setting PreserveAlpha to True.

This function supports in-place operation, that is Dst may be the same as Src.

See Also

AlphaToGrayscale, TCustomBitmap32


CopyComponents

procedure CopyComponents(
Dst: TCustomBitmap32;
Src: TCustomBitmap32;
Components: TColor32Components); overload;

procedure CopyComponents(
Dst: TCustomBitmap32;
DstX: Integer;
DstY: Integer;
Src: TCustomBitmap32;
SrcRect: TRect;
Components: TColor32Components);overload;

Description

CopyComponents copies the provided TColor32Components from Source to Destination (read: no blending etc. is involved). The first version doesn't take specific source and destination settings and will therefore resize (and implicitly clear) destination so it is same size as the source. The second version will not modify size of the destination and therefore leaves the components not overwritten by the operation untouched.

See Also

ApplyBitmask, Color Types, TCustomBitmap32, Rectangle Types


CreateBitmask

function CreateBitmask(Components: TColor32Components): TColor32; overload;

This function takes a set of TColor32Component and creates a TColor32. If a given component is present in the set, the result component will get the value 255; if not present the result component will be zero. The context of application is to prepare a Bitmask parameter for the routine ApplyBitmask. To construct bitmasks containing any number in range [0..255] per component, use Color32.

See Also

ApplyBitmask, Color32, Color Types, Color Types, Color Types


IntensityToAlpha

procedure IntensityToAlpha(Dst, Src: TCustomBitmap32);

Description

This function transforms the color intensity, stored in RGB channels of Src bitmap into the alpha channel in Dst. If necessary, the Dst bitmap is resized to fit Src dimesions.

The intensity is calculated using the Intensity function.

The function writes only the alpha component into Dst. Other channels remain intact (provided dimensions of Dst and Src match before IntensityToAlpha call).

IntensityToAlpha is useful when it is necessary to load an alpha channel stored in as an image.

The in-place operation is fully supported, that is Dst may be the same as Src.

See Also

AlphaToGrayscale, Intensity, TCustomBitmap32


Invert

procedure Invert(Dst, Src: TCustomBitmap32; Components : TColor32Components = [ccAlpha, ccRed, ccGreen, ccBlue]);

Description

Inverts the given set of components. If no component set is provided all color components, including the alpha component will be inverted.

This function supports in-place operation, that is Dst may be the same as Src.

See Also

InvertRGB, Color Types, TCustomBitmap32


InvertRGB

procedure InvertRGB(Dst, Src: TCustomBitmap32);

Description

Inverts RGB color channels, and copies the alpha channel without inversion. If necessary, the Dst bitmap is resized to fit Src dimensions. This function is equal to calling Invert with Components = [ccRed, ccGreen, ccBlue].

This function supports in-place operation, that is Dst may be the same as Src.

See Also

Invert, TCustomBitmap32


GR32_Image

GR32_Image.pas contains visual components for image storing and visualization.

Contents

Types | Classes | Constants
TPaintBoxOptions | TBitmap32Collection | Paint Stage Constants
TPaintStage | TBitmap32Item |
TRepaintMode | TBitmap32List |
TScaleMode | TCustomImage32 |
TScrollBarVisibility | TCustomImgView32 |
TSizeGripStyle | TCustomPaintBox32 |
 | TImage32 |
 | TImgView32 |
 | TIVScrollProperties |
 | TPaintBox32 |
 | TPaintStages |


TPaintBoxOptions

type TPaintBoxOptions = (pboWantArrowKeys, pboAutoFocus);

Description

TPaintBoxOptions is the type for the Options property in TCustomPaintBox32 and its descendants.

See Also

TCustomPaintBox32.Options, TCustomPaintBox32


TPaintStage

type TPaintStage = record
DsgnTime: Boolean;
RunTime: Boolean;
Stage: Cardinal; // a PST_* constant
Parameter: Cardinal; // an optional parameter
end;

type PPaintStage = ^TPaintStage;

Description

Defines a drawing stage in TCustomImage32.

DsgnTime — indicates that the stage must be executed at design-time;

RunTime — indicates that the stage must be executed at run-time;

Stage — is one of the Paint Stage Constants, which specifies the stage action;

Parameter — is an optional parameter used in some paint stages.

See Also

Paint Stage Constants, Paint Stages, TCustomImage32.PaintStages, Repaint Optimization, TCustomImage32


TRepaintMode

type TRepaintMode = (rmFull, rmDirect, rmOptimizer);

Description

TRepaintMode is the type for the RepaintMode property in TCustomPaintBox32 and its descendants.

See Also

TCustomPaintBox32.RepaintMode, TCustomPaintBox32


TScaleMode

type TScaleMode = (smNormal, smStretch, smScale, smResize, smOptimal, smOptimalScaled);

Description

TScaleMode is a type for the ScaleMode property in TCustomImage32.

See Also

TCustomImage32.ScaleMode, TCustomImage32


TScrollBarVisibility

type TScrollBarVisibility = (svAlways, svHidden, svAuto);

Description

TScrollBarVisibility is the type for the Visibility property in TIVScrollProperties.

See Also

TIVScrollProperties, TIVScrollProperties.Visibility


TSizeGripStyle

type TSizeGripStyle = (sgAuto, sgNone, sgAlways);

Description

TSizeGripStyle is a type for the SizeGrip property in TCustomImgView, which determines appearance of a sizing grip at the bottom-right corner.

See Also

GR32_Image, TCustomImgView32.SizeGrip


Paint Stage Constants

Paint stage constants specify the type of operation associated with a paint stage in TCustomImage32 and its descendants.

There is seven types of paint stages, which can be used by TCustomImage32 to paint its contents. Each paint stage has 'PST_' prefix:

Stage Name | Value | Description
PST_CUSTOM | 1 | Calls the OnPaintStage event
PST_CLEAR_BUFFER | 2 | Clears the buffer
PST_CLEAR_BACKGND | 3 | Clears visible buffer area
PST_DRAW_BITMAP | 4 | Draws a scaled bitmap image
PST_DRAW_LAYERS | 5 | Draws layers
PST_CONTROL_FRAME | 6 | Draws a dotted frame around the control
PST_BITMAP_FRAME | 7 | Draws a dotted frame around the scaled bitmap image

See Also

Paint Stages, TCustomImage32


TBitmap32Collection

Hierarchy

TCollection

Description

TBitmap32Collection is a collection of TBitmap32Item objects.

Reference

Methods | Properties
In TBitmap32Collection:
Add | Items
Create |

See Also

TBitmap32Item


Add

TBitmap32Collection.Add

function Add: TBitmap32Item;

Description

Creates a new instance of the bitmap item with the empty bitmap, adds it to the collection and returns reference to the new bitmap item.

Alternatively, you may use TBitmap32Item.Create method to add new items to the collection.

See Also

TBitmap32Item.Create, TBitmap32Item


Create

TBitmap32Collection.Create

constructor Create(AOwner: TPersistent; ItemClass: TBitmap32ItemClass);

type TBitmap32ItemClass = class of TBitmap32Item;

Description

Creates an instance of TBitmap32Collection.

ItemClass specifies must specify TBitmap32Item or its descendant. When calling collection's Add method it will create instances of the class specified in ItemClass parameter.

See Also

Add, TBitmap32Collection, TBitmap32Item


Items

TBitmap32Collection.Items

property Items[Index: Integer]: TBitmap32Item;

Description

Provides indexed access to stored bitmap items.

Bitmap items are instances of TBitmap32Item object. Each bitmap item, in turn, contains a TBitmap32 object, accessible through its Bitmap property.

The number of items may be obtained by reading inherited Count property.

See Also

TBitmap32Item.Bitmap, TBitmap32, TBitmap32Item


TBitmap32Item

Hierarchy

TCollectionItem

Description

TBitmap32Item is a simple descendant of standard TCollectionItem, specialized for storing bitmaps.

Reference

Methods | Properties
In TBitmap32Item:
Create | Bitmap
Destroy |


Create

TBitmap32Item.Create

constructor Create(Collection: TCollection); override;

Description

Creates an instance of TBitmap32Item.

When creating bitmap items at run time, pass the corresponding TBitmap32Collection object as the parameter.

Alternatively, you may use TBitmap32Collection.Add method to create new bitmap items:

var
BitmapCollection: TBitmap32Collection;
B1, B2: TBitmap32Item;
begin
BitmapCollection := TBitmap32Collection.Create;
try
B1 := TBitmap32Item.Create(BitmapCollection);
B2 := BitmapCollection.Add;
// some operations with B1, B2...
finally
BitmapCollection.Free;
end;
end;

Note, that it is not necessary to call the Free method for bitmap items, since they are owned by the collection.

See Also

TBitmap32Collection.Add, TBitmap32Collection, TBitmap32Item


Destroy

TBitmap32Item.Destroy

destructor Destroy; override;

Description

Removes a bitmap item from the collection, destroys it and frees allocated memory.

Do not call Destroy in your application, use standard Free method instead.

Since bitmap items are owned by the collection, they all are destroyed automaticaly when the collection is destroyed. There is no need to call Free method for bitmap items unless you want them to be explicitly destroyed before the collection is destroyed.

See Also

TBitmap32Collection.Items


Bitmap

TBitmap32Item.Bitmap

property Bitmap: TBitmap32;

Description

Provides access to the contained bitmap.

See Also

TBitmap32


TBitmap32List

Hierarchy

TComponent

Description

A VCL wrapper around TBitmap32Collection object.

TBitmap32List provides simple means for storing bitmaps in design time.

The TBitmap32List object is quite different from the standard TImageList.

While TImageList, in fact, stores all images on a single bitmap, and all of its images have the same dimensions, TBitmap32List stores its items as independent bitmaps, which means, it can contain bitmaps of different sizes.

Reference

Methods | Properties
In TBitmap32List:
Create | Bitmap
Destroy | Bitmaps

See Also

TBitmap32Collection


Create

TBitmap32List.Create

constructor Create(AOwner: TComponent); override;

Description

Creates an instance of TBitmap32List.

See Also

TBitmap32List


Destroy

TBitmap32List.Destroy

destructor Destroy; override;

Description

Destroys the contained bitmap collection, including all the bitmaps in it, then calls the inherited destructor.

Do not call Destroy in your application, use standard Free method instead.


Bitmap

TBitmap32List.Bitmap

property Bitmap[Index: Integer]: TBitmap32; default;

Description

Provides an indexed access to stored bitmaps.

Using Bitmap[Index] is the same as using Bitmaps[Index].Bitmap.

See Also

Bitmaps, TBitmap32


Bitmaps

TBitmap32List.Bitmaps

property Bitmaps: TBitmap32Collection;

Description

Provides indexed access to contained TBitmap32Collection object. The total number of items may be obtained through collection's Count property.

See Also

TBitmap32Collection


TCustomImage32

Hierarchy

TCustomControl

|

TCustomPaintBox32

Description

A visual control capable of displaying bitmap images.

TCustomImage32 is a base class for TImage32. In addition to TCustomPaintBox32 behavior, it contains an easy-manageable bitmap and a collection of layers.

It introduces several properties to determine how the bitmap image is displayed within the boundaries of the control.

For more information on how to use TCustomImage32 and its descendants, see Using TImage32.

Reference

Fields | Methods | Properties | Events
In TCustomImage32:
 | BeginUpdate | Bitmap | OnBitmapResize
 | BitmapToControl | BitmapAlign | OnChange
 | Changed | Layers | OnGDIOverlay
 | ControlToBitmap | OffsetHorz | OnInitStages
 | Create | OffsetVert | OnMouseDown
 | Destroy | PaintStages | OnMouseMove
 | EndUpdate | Scale | OnMouseUp
 | ExecBitmapFrame | ScaleMode | OnPaintStage
 | ExecClearBackgnd | ScaleX | OnPixelCombine
 | ExecClearBuffer | ScaleY | OnScaleChange
 | ExecControlFrame |  |
 | ExecCustom |  |
 | ExecDrawBitmap |  |
 | ExecDrawLayers |  |
 | GetPictureRect |  |
 | GetPictureSize |  |
 | Resize |  |
 | SetupBitmap |  |
In TCustomPaintBox32:
 | DoPaintBuffer | Buffer | OnMouseEnter
 | Flush | BufferOversize | OnMouseLeave
 | ForceFullInvalidate | BufferValid |
 | GetViewportRect | Options |
 | Invalidate | RepaintMode |
 | Loaded |  |
 | SetBounds |  |

See Also

Examples, Examples, Examples, TCustomPaintBox32, TImage32, Using TImage32


BeginUpdate

TCustomImage32.BeginUpdate

procedure BeginUpdate; virtual;

Description

Disables change notifications until the paired EndUpdate method is called.

BeginUpdate...EndUpdate blocks may be nested.

See Also

EndUpdate, OnChange


BitmapToControl

TCustomImage32.BitmapToControl

function BitmapToControl(const APoint: TPoint): TPoint;

Description

Transforms point coordinates from the reference frame of bitmap image to control's reference frame.

See Also

Bitmap Image, ControlToBitmap, Point Types


Changed

TCustomImage32.Changed

procedure Changed; virtual;

Description

In case the update notification is not masked with BeginUpdate, Changed invalidates the control and then calls the OnChange event.

See Also

BeginUpdate, EndUpdate, TCustomPaintBox32.Invalidate, OnChange


ControlToBitmap

TCustomImage32.ControlToBitmap

function ControlToBitmap(const APoint: TPoint): TPoint;

Description

Transforms point coordinates from control's reference frame to the reference frame of bitmap image.

See Also

Bitmap Image, BitmapToControl, Point Types


Create

TCustomImage32.Create

constructor Create(AOwner: TComponent); override;

Description

Creates an instance of TCustomImage32.

After calling the inherited constructor, Create initializes the following properties:

  • BitmapAlign to baTopLeft;
  • OffsetHorz to 0;
  • OffsetVert to 0;
  • Scale to 1.0;
  • ScaleMode to smNormal;

See Also

BitmapAlign, OffsetHorz, OffsetVert, Scale, ScaleMode, TCustomPaintBox32


Destroy

TCustomImage32.Destroy

destructor Destroy; override;

Description

Destroys an instance of TCustomImage32, freeing the memory allocated to bitmap image and layers.

Do not call the Destroy directly in your application. Call the standard Free method instead.

See Also

TCustomImage32


EndUpdate

TCustomImage32.EndUpdate

property EndUpdate: TNotifyEvent;

Description

Re-enables generation of the OnChange event, masked with BeginUpdate method.

BeginUpdate...EndUpdate pairs may be safely nested.

See Also

BeginUpdate, OnChange


ExecBitmapFrame

TCustomImage32.ExecBitmapFrame

procedure ExecBitmapFrame(Dest: TBitmap32; Stage: Integer); virtual;

Description

Draw a dotted frame around the scaled bitmap image in design time.

This method is called by the control when it executes PST_BITMAP_FRAME paint stage.

See Also

Paint Stages, TBitmap32


ExecClearBackgnd

TCustomImage32.ExecClearBackgnd

procedure ExecClearBuffer(Dest: TBitmap32; Stage: Integer); virtual;

Description

Clears the visible area of the buffer with the color specified in the Color property of the control.

This method is called by the control when it executes PST_CLEAR_BACKGND paint stage.

See Also

Paint Stages, TBitmap32


ExecClearBuffer

TCustomImage32.ExecClearBuffer

procedure ExecClearBuffer(Dest: TBitmap32; Stage: Integer); virtual;

Description

Clears the whole buffer with the color specified in the Color property of the control.

This method is called by the control when it executes PST_CLEAR_BUFFER paint stage. Note, however, that by default, TCustomImage32 does not execute PST_CLEAR_BUFFER stage, instead of it it uses PST_CLEAR_BACKGND, which works faster in some cases.

See Also

Paint Stages, TBitmap32, TCustomImage32


ExecControlFrame

TCustomImage32.ExecControlFrame

procedure ExecControlFrame(Dest: TBitmap32; Stage: Integer); virtual;

Description

Draw a dotted frame around control boundaries in design-ime.

This method is called by the control when it executes PST_CONTROL_FRAME paint stage.

See Also

Paint Stages, TBitmap32


ExecCustom

TCustomImage32.ExecCustom

procedure ExecCustom(Dest: TBitmap32; Stage: Integer); virtual;

Description

Calls the OnPaintStage event.

This method is called by the control when it executes PST_CUSTOM stage.

See Also

OnPaintStage, Paint Stages, TBitmap32


ExecDrawBitmap

TCustomImage32.ExecDrawBitmap

procedure ExecDrawBitmap(Dest: TBitmap32; Stage: Integer); virtual;

Description

Paints the bitmap image.

This method is called by the control when it executes PST_DRAW_BITMAP stage.

See Also

Paint Stages, TBitmap32


ExecDrawLayers

TCustomImage32.ExecDrawLayers

procedure ExecDrawLayers(Dest: TBitmap32; Stage: Integer); virtual;

Description

Paints layers using the layer mask of the corresponding stage.

This method is called by the control when it executes PST_DRAW_LAYERS stage.

See Also

Paint Stages, TBitmap32


GetPictureRect

TCustomImage32.GetPictureRect

function GetPictureRect: TRect;

Description

Returns the location of the bitmap image after an appropriate ScaleMode and BitmapAlign is applied. In bmTile ScaleMode it returns the location of a top-left tile.

See Also

Bitmap Image, BitmapAlign, GetPictureSize, ScaleMode, Rectangle Types


GetPictureSize

TCustomImage32.GetPictureSize

function GetPictureSize: TSize;

Description

Returns the size of the bitmap image after an appropriate ScaleMode is applied. In bmTile ScaleMode it returns the size of a tile.

See Also

Bitmap Image, GetPictureRect, ScaleMode, TSize


Resize

TCustomImage32.Resize

procedure Resize; override;

Description

Copyright ©2000-2012 Alex Denisov and the Graphics32 Team - Graphics32 v1.9.1 - Build on 28-August-2012


SetupBitmap

TCustomImage32.SetupBitmap

procedure SetupBitmap(
DoClear: Boolean = False;
ClearColor: TColor32 = $FF000000);

Description

Sets the size of the bitmap image to the size of the buffered area. This method does not account for current ScaleMode.

If DoClear = True, the resized image will be filled with a color specified in the ClearColor parameter.

See Also

Bitmap Image, TCustomPaintBox32.GetViewportRect, ScaleMode, Color Types


Bitmap

TCustomImage32.Bitmap

property Bitmap: TBitmap32;

Description

Provides access to the bitmap image.

See Also

Bitmap Image, TBitmap32


BitmapAlign

TCustomImage32.BitmapAlign

property BitmapAlign: TBitmapAlign;

type TBitmapAlign = (baTopLeft, baCenter, baTile, baCustom);

Description

Specifies how the bitmap image is located withing the control's boundaries.

Note, that in TCustomImgView32 this property should always remain baCustom.

See Also

Bitmap Image, TCustomImgView32


Layers

TCustomImage32.Layers

property Layers: TLayerCollection;

Description

Provides access to the layer collection.

See Also

TLayerCollection, Using Layers


OffsetHorz

TCustomImage32.OffsetHorz

property OffsetHorz: Single;

Description

Specifies the horizontal offset of the bitmap image in baCustom BitmapAlign mode

See Also

Bitmap Image, BitmapAlign


OffsetVert

TCustomImage32.OffsetVert

property OffsetVert: Single;

Description

Specifies the vertical offset of the bitmap image in baCustom BitmapAlign mode

See Also

Bitmap Image, BitmapAlign


PaintStages

TCustomImage32.PaintStages

property PaintStages: TPaintStages;

Description

Provides access to paint stages of the control, allowing to customize the order in which it repaints itself.

See Also

Paint Stages, TPaintStages


Scale

TCustomImage32.Scale

property Scale: Single;

Description

Specifies the X and Y scale of the bitmap image when ScaleMode is smScale or smOptimalScaled.

Warning: do not set too small scales in baTile BitmapAlign mode, as this can have severe impact on performance.

See Also

Bitmap Image, BitmapAlign, Scale, ScaleMode, ScaleX


ScaleMode

TCustomImage32.ScaleMode

property ScaleMode: TScaleMode;

type TScaleMode = (smNormal, smStretch, smScale, smResize, smOptimal, smOptimalScaled);

Description

Specifies the current scale mode for the bitmap image.

smNormal will display the bitmap image with its original size;

smStretch will stretch the bitmap image to fit the control's boundaries;

smResize will proportionally resize the bitmap image to fit the control's boundaries;

smScale will proportionally scale the bitmap image using the factor provided by the Scale property;

smOptimal will proportionally fit the bitmap image into the control's boundaries if the viewport is smaller than the image size. Otherwise it will be displayed with its original size;

smOptimalScaled will proportionally fit the bitmap image into the control's boundaries if the viewport is smaller than the image size multiplied by the Scale property. Otherwise it will be displayed with its original size.

Note, that TCustomImgView32 descendants only support smScale, smOptimal and smOptimalScaled mode.

See Also

Bitmap Image, Scale, TCustomImgView32, TScaleMode


ScaleX

TCustomImage32.ScaleX

property ScaleX: Single;

Description

Specifies the X scale of the bitmap image when ScaleMode is smScale or smOptimalScaled.

Warning: do not set too small scales in baTile BitmapAlign mode, as this can have severe impact on performance.

See Also

Bitmap Image, BitmapAlign, Scale, ScaleMode, ScaleY


ScaleY

TCustomImage32.ScaleY

property ScaleY: Single;

Description

Specifies the Y scale of the bitmap image when ScaleMode is smScale or smOptimalScaled.

Warning: do not set too small scales in baTile BitmapAlign mode, as this can have severe impact on performance.

See Also

Bitmap Image, BitmapAlign, Scale, ScaleMode, ScaleX


OnBitmapResize

TCustomImage32.OnBitmapResize

property OnBitmapResize: TNotifyEvent;

Description

This event is generated after the bitmap image is resized, that is its Width or Height property changes. OnBitmapResize is not generated when Scale or ScaleMode is changed.

See Also

TCustomMap.Height, Scale, ScaleMode, TCustomMap.Width


OnChange

TCustomImage32.OnChange

property OnChange: TNotifyEvent;

Description

OnChange is an abstract change notification event, which is called by some of the descendants of TCustomPaintBox32 immediately after changes have been made to their contents.

In TCustomImage32, for example, this includes redirection of change notification events from the contained bitmap and from layers.

This event, however, is not called by TCustomPaintBox32 control itself, unless you call the Changed method explicitly.

Change notification may be disabled with BeginUpdate call and re-enabled with EndUpdate call.

See Also

BeginUpdate, Changed, EndUpdate, TCustomImage32, TCustomPaintBox32


OnGDIOverlay

TCustomImage32.OnGDIOverlay

property OnGDIOverlay: TNotifyEvent;

Description

[ Note: Most likely this event will be removed in future versions. Do not use it ]

This event is called after the image has been combined with layers in the back-buffer and copied to the screen. In the event handler you can provide additional drawing using the standard Canvas of the control.

Drawing at this stage will not affect the contents of the back-buffer.

See Also

OnPaintStage, Paint Stages


OnInitStages

TCustomImage32.OnInitStages

property OnInitStages: TNotifyEvent;

Description

OnInitStages is called by TCustomImage32 in the process of initialization right after it finishes building default list of paint stages. You may also alter the stages in the OnCreate event handler of the owner form or anywhere else in you program.

See Also

Paint Stages, TCustomImage32


OnMouseDown

TCustomImage32.OnMouseDown

property OnMouseDown: TImgMouseEvent;

type TImgMouseEvent = procedure(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer; Layer: TCustomLayer) of object;

Description

This event occurs when user pushes the mouse button in the image area. The Layer parameter indicates the layer under the mouse, or nil in case the mouse is over the background area.

Whether the layer is under the mouse or not, is determined by the HitTest function and by the LOB_MOUSE_EVENTS bit in LayerOptions. The top-most layer which passes the test is passed into the Layer parameter of the event.

Note, that once mouse was pressed, the layer (or the background) captures the mouse messages until the mouse button is released.

See Also

TCustomLayer.HitTest, TCustomLayer.LayerOptions, OnMouseMove, OnMouseUp, TCustomLayer


OnMouseMove

TCustomImage32.OnMouseMove

property OnMouseMove: TImgMouseMoveEvent;

type TImgMouseMoveEvent = procedure(Sender: TObject; Shift: TShiftState; X, Y: Integer; Layer: TCustomLayer) of object;

Description

This event is fired while the mouse is dragged over the image. Layer indicates the layer under the mouse, nil – when there is no layer under the mouse, or the layer which has captured mouse events.

See Also

OnMouseDown, OnMouseUp, TCustomLayer


OnMouseUp

TCustomImage32.OnMouseUp

property OnMouseUp: TImgMouseEvent;

type TImgMouseEvent = procedure(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer; Layer: TCustomLayer) of object;

Description

This event occurs when the mouse button is released. Layer indicates the layer under the mouse, nil – when there is no layer under the mouse, or the layer which has captured mouse events.

See Also

Changed, TCustomLayer


OnPaintStage

TCustomImage32.OnPaintStage

property OnPaintStage: TPaintStageEvent;

type TPaintStageEvent = procedure(Sender: TObject; Dest: TBitmap32; StageNum: Cardinal) of object;

Description

An event, called by the control while it repaints itself. By default, TCustomImage32 does not generate OnPaintStage events, but this can be changed by adding PST_CUSTOM paint stages.

In the event handler, do not paint to Buffer directly, use the passed Dest parameter instead.

See Also

TCustomPaintBox32.Buffer, Paint Stages, TBitmap32, TCustomImage32


OnPixelCombine

TCustomImage32.OnPixelCombine

property OnPixelCombine: TPixelCombineEvent;

type TPixelCombineEvent = procedure(F: TColor32; var B: TColor32; M: TColor32) of object;

Description

This event is redirected from the bitmap image, in order to make it accessible in the Delphi's Object Manager. There is no difference between using TCustomImage32.OnPixelCombine and TBitmap32.OnPixelCombine.

See Also

TCustomBitmap32.OnPixelCombine, Color Types, TCustomImage32, TPixelCombineEvent


OnScaleChange

TCustomImage32.OnScaleChange

property OnScaleChange: TNotifyEvent;

Description

OnScaleChange is change notification event, which is called whenever the Scale property changes.

See Also

Changed, Scale, ScaleX, TCustomImage32


TCustomImgView32

Hierarchy

TCustomControl

|

TCustomPaintBox32

|

TCustomImage32

Description

TCustomImgView32 is an extention of TCustomImage32, which additionaly provides a couple of scroll bars to simplify operations with images larger then the control area.

Most of its behavior is inherited from TCustomImage32, however some properties are obsolete:

  • BitmapAlign is no longer used, since the control is always in baCustom mode;
  • ScaleMode is no longer used, the control is always in smScale mode;

For more information on how to use TCustomImgView32 and its descendants, see Using TImage32.

Reference

Fields | Methods | Properties | Events
In TCustomImgView32:
 | Create | Centered | OnScroll
 | Destroy | OverSize |
 | GetViewportRect | ScrollBars |
 | Loaded | SizeGrip |
 | Resize |  |
 | Scroll |  |
 | ScrollToCenter |  |
In TCustomImage32:
 | BeginUpdate | Bitmap | OnBitmapResize
 | BitmapToControl | BitmapAlign | OnChange
 | Changed | Layers | OnGDIOverlay
 | ControlToBitmap | OffsetHorz | OnInitStages
 | EndUpdate | OffsetVert | OnMouseDown
 | ExecBitmapFrame | PaintStages | OnMouseMove
 | ExecClearBackgnd | Scale | OnMouseUp
 | ExecClearBuffer | ScaleMode | OnPaintStage
 | ExecControlFrame | ScaleX | OnPixelCombine
 | ExecCustom | ScaleY | OnScaleChange
 | ExecDrawBitmap |  |
 | ExecDrawLayers |  |
 | GetPictureRect |  |
 | GetPictureSize |  |
 | SetupBitmap |  |
In TCustomPaintBox32:
 | DoPaintBuffer | Buffer | OnMouseEnter
 | Flush | BufferOversize | OnMouseLeave
 | ForceFullInvalidate | BufferValid |
 | Invalidate | Options |
 | SetBounds | RepaintMode |

See Also

TCustomImage32, Using TImage32


Create

TCustomImgView32.Create

constructor Create(AOwner: TComponent); override;

Description

Creates an instance of TCustomImgView32.

After calling the inherited constructor, Create initializes the Centered property to True.

See Also

Centered, TCustomImgView32


Destroy

TCustomImgView32.Destroy

destructor Destroy; override;

Description

Destroys the instance of TCustomImgView32 class and frees all associated memory.

Do not call Destroy directly, use Free method instead.

See Also

TCustomImgView32


GetViewportRect

TCustomImgView32.GetViewportRect

function GetViewportRect: TRect; override;

Description

This property is overriden to return the rectangle, corresponding to the control dimensions minus the area covered by the scroll bars.

See Also

TIVScrollProperties.Size, Rectangle Types


Loaded

TCustomImgView32.Loaded

procedure Loaded; override;

Description

Loaded is overriden to adjust positions of scroll bars after the control loads it properties from the DFM file.

Normally, you sould not use it in your application.


Resize

TCustomImgView32.Resize

procedure Resize; override;

Description

Resize is overriden to adjust positions of scroll bars after the control resizes.

Normally, you sould not use it in your application.


Scroll

TCustomImgView32.Scroll

procedure Scroll(Dx. Dy: Integer);

Description

Scrolls the viewport by the offsets given by the Dx and Dy parameters.


ScrollToCenter

TCustomImgView32.ScrollToCenter

procedure ScrollToCenter(X, Y: Integer);

Description

Relatively scrolls the center of the viewport to the X and Y coordinates.


Centered

TCustomImgView32.Centered

property Centered: Boolean;

Description

Indicates the alignmet of the container bitmap image. When Centered is True (default) the image is automatically positioned at the center of the control, otherwise it is located at the top-left corner.


OverSize

TCustomImgView32.OverSize

property OverSize: Integer;

Description

This property introduces a frame of OverSize pixels in each direction around the bitmap.
This will keep the bitmap scrollable even if it is scaled to fit the viewport. OverSize is set to 0 by default.


ScrollBars

TCustomImgView32.ScrollBars

property ScrollBars: TIVScrollProperties;

Description

Controls appearance of scroll bars.

The scroll bars in TCustomImgView32 are of the TCustomRangeBar type. Use ScrollBars to control properties of the vertical and horizontal scroll bar simultaneously.

See Also

TCustomImgView32, TCustomRangeBar, TIVScrollProperties


SizeGrip

TCustomImgView32.SizeGrip

property SizeGrip: TSizeGripStyle;

type TSizeGripStyle = (sgAuto, sgNone, sgAlways);

Description

Modify the SizeGrip property to control the appearance of the resizing grip at the lower-right corner of the control:

In shAuto mode, visibuility of the grip is determined similar to tat in other standard controls (e.g. TScrollBox), it becomes visible when control is client-aligned (if it has parents, they should be client-aligned as well).

Use snNone and sgAlways styles to specify its appearance explicitly.

See Also

TSizeGripStyle


OnScroll

TCustomImgView32.OnScroll

property OnScroll: TNotifyEvent;

Description

This event is generated when user scrolls the image using scroll bars.


TCustomPaintBox32

Hierarchy

TCustomControl

Description

TCustomPaintBox32 is a common ancestor for TPaintBox32 and TCustomImage32 objects.

In addition to properties, inherited from TCustomControl, it provides optimized double buffering. The back buffer is a TBitmap32 object, which stores an image data before flushing it to the screen.

Since TCustomPaintBox32 is double buffered, there is no need to redraw its contents every time the control receives WM_PAINT message, as with standard TPaintBox. The repainting is still required when the control is resized.

Reference

Fields | Methods | Properties | Events
In TCustomPaintBox32:
 | Destroy | Buffer | OnMouseEnter
 | DoPaintBuffer | BufferOversize | OnMouseLeave
 | Flush | BufferValid |
 | ForceFullInvalidate | Options |
 | GetViewportRect | RepaintMode |
 | Invalidate |  |
 | Loaded |  |
 | Resize |  |
 | SetBounds |  |

See Also

TBitmap32, TCustomImage32, TPaintBox32


Destroy

TCustomPaintBox32.Destroy

destructor Destroy; override;

Description

Destroys an instance of TCustomPaintBox32 object and frees all associated memory.

Do not call Destroy directly, use Free method instead.

See Also

TCustomPaintBox32


DoPaintBuffer

TCustomPaintBox32.DoPaintBuffer

procedure DoPaintBuffer; virtual;

Description

DoPaintBuffer is an abstract virtual method, called by the controll during its repainting.


Flush

TCustomPaintBox32.Flush

procedure Flush; overload;

procedure Flush(const SrcRect: TRect); overload;

Description

Immediately copies the contents of the buffer, or its part passed in SrcRect to the screen. Use this function when you want to bypass normal Windows invalidating/repainting procedure, for example when the buffer is painted by the other thread.

Both functions are thread-safe.

See Also

Rectangle Types


ForceFullInvalidate

TCustomPaintBox32.ForceFullInvalidate

procedure ForceFullInvalidate;

Description

ForceFullInvalidate is similar to Invalidate. However, it will override the repaint optimizer for the following deferred repaint.

See Also

Invalidate, Repaint Optimization, RepaintMode


GetViewportRect

TCustomPaintBox32.GetViewportRect

function GetViewportRect: TRect; virtual; // protected

Description

Returns coordinates of the buffered area relative to control's client area. By default, it coincides with the control's client rectangle, that is, the function returns (0, 0, ClientWidth, ClientHeight) rectangle.

Descendants may override this method and return a different rectangle if they have unbuffered areas, like scroll bars.

See Also

Rectangle Types


Invalidate

TCustomPaintBox32.Invalidate

procedure Invalidate; override;

Description

Invalidate is overriden from TWinControl. In addition to standard behavior, it also invalidates the buffer content, so that the buffer gets actually updated during the following paint procedure.

You do not have to call this method explicitly in your application.


Loaded

TCustomPaintBox32.Loaded

procedure Loaded; override;

Description

Loaded is overriden from TWinControl to keep the buffer dimensions consistent with control's dimensions. You do not have to call this method explicitly in your application.


Resize

TCustomPaintBox32.Resize

procedure Resize; override;

Description

Resize is overriden from TWinControl. It keeps the size of the buffer consistent with control's dimensions after the control resizes. Normally, you will not call this method in your applications.

Whether the buffer is actually resized or not is influenced by the BufferOversize property.

Resizing of the control will also invalidate its buffer.

Resize generates the standard OnResize event as well.

See Also

BufferOversize


SetBounds

TCustomPaintBox32.SetBounds

procedure SetBounds(ALeft, ATop, AWidth, AHeight: Integer); override;

Description

SetBounds is overriden from TWinControl to keep buffer dimensions consistent with the control size.

You do not have to call this method explicitly in your application.


Buffer

TCustomPaintBox32.Buffer

property Buffer: TBitmap32; // Read only;

Description

Provides direct access to the back buffer.

Note that the actual size of the buffered may be up to BufferOversize pixels larger then the buffered area.

See Also

BufferOversize, BufferValid, TBitmap32


BufferOversize

TCustomPaintBox32.BufferOversize

property BufferOversize: Integer; // protected

Description

BufferOversize specifies how the back buffer is reallocated when the control is resized.

When BufferOversize equals 0, the back buffer is reallocated each time the control is resized to suite the new control dimensions.

When set to some positive value (40 by default), the back buffer is allowed to be up to BufferOversize pixels larger then the control is in each direction. The buffer resizing algorithm tracks size changes and reallocates the buffer only when its size becomes smaller than size of the buffered area or when the difference between the sizes exceeds the specified amount of pixels.

See Also

Buffer, GetViewportRect


BufferValid

TCustomPaintBox32.BufferValid

property BufferValid: Boolean; // protected

Description

BufferValid specifies if the current content of the Buffer bitmap is up-to-date and whether the buffer needs to be repainted.

When TCustomPaintBox32 repaints itself, it checks whether the buffer is valid. If BufferValid is True, the control simply flushes its contents to the screen, otherwise, it executes DoPaintBuffer method, which updates the buffer and sets BufferValid to True, then it copies content of the buffer to the screen.

Normally, this property should not be accessed in your application, since TCustomPaintBox32 tracks the buffer state and updates it automatically.

See Also

Buffer, DoPaintBuffer, TCustomPaintBox32


Options

TCustomPaintBox32.Options

property Options: TPaintBoxOptions;

type TPaintBoxOptions = set of (pboWantArrowKeys, pboAutoFocus);

Description

This property controls additional options of the paint box and its descendants:

pboWantArrowKeys - indicates whether the keyboard arrow keys appear in OnKeyDown event;

pboAutoFocus - indicates that the paint box automatically captures keyboard focus when clicked with the mouse. The focus is acquired before the OnMouseDown event is fired.

See Also

TPaintBoxOptions


RepaintMode

TCustomPaintBox32.RepaintMode

property RepaintMode: TRepaintMode;

type TRepaintMode = (rmFull, rmDirect, rmOptimizer);

Description

This property controls the way repaints of the contents are handled by TCustomPaintBox32 and its descendants:

rmFull - indicates whether always to repaint everything;

rmDirect - indicates to use a direct repaint rather than a deferred invalidation. Please note, that this mode is not supported for layer supporting control like TCustomImage32 and its descendants;

rmOptimizer - indicates to use the repaint optimizer to just repaint changed areas. Especially layer operations benefit from this mode.

See Also

Repaint Optimization, TCustomImage32, TPaintBoxOptions


OnMouseEnter

TCustomPaintBox32.OnMouseEnter

property OnMouseEnter: TNotifyEvent;

Description

OnMouseEnter is called by TPaintBox32 when the Mouse cursor has entered the control.

See Also

TCustomPaintBox32


OnMouseLeave

TCustomPaintBox32.OnMouseLeave

property OnMouseLeave: TNotifyEvent;

Description

OnMouseLeave is called by TPaintBox32 when the Mouse cursor has left the control.

See Also

TCustomPaintBox32


TImage32

Hierarchy

TCustomControl

|

TCustomPaintBox32

|

TCustomImage32

Description

An image displaying control.

TImage32 implements the generic behavior introduced in TCustomImage32. It publishes some inherited properties from TCustomImage32, but does not introduce any new behavior.

TImage32 allows loading of its Bitmap property from supported image files in design-time using a property editor, associated with TBitmap32 objects. The same property editor is activated when you double-click the control in design-time.

For more information on TImage32, see Using TImage32.

Reference

Fields | Methods | Properties | Events
In TCustomImage32:
 | BeginUpdate | Bitmap | OnBitmapResize
 | BitmapToControl | BitmapAlign | OnChange
 | Changed | Layers | OnGDIOverlay
 | ControlToBitmap | OffsetHorz | OnInitStages
 | Create | OffsetVert | OnMouseDown
 | Destroy | PaintStages | OnMouseMove
 | EndUpdate | Scale | OnMouseUp
 | ExecBitmapFrame | ScaleMode | OnPaintStage
 | ExecClearBackgnd | ScaleX | OnPixelCombine
 | ExecClearBuffer | ScaleY | OnScaleChange
 | ExecControlFrame |  |
 | ExecCustom |  |
 | ExecDrawBitmap |  |
 | ExecDrawLayers |  |
 | GetPictureRect |  |
 | GetPictureSize |  |
 | Resize |  |
 | SetupBitmap |  |
In TCustomPaintBox32:
 | DoPaintBuffer | Buffer | OnMouseEnter
 | Flush | BufferOversize | OnMouseLeave
 | ForceFullInvalidate | BufferValid |
 | GetViewportRect | Options |
 | Invalidate | RepaintMode |
 | Loaded |  |
 | SetBounds |  |

See Also

Examples, Examples, Examples, TBitmap32, TCustomImage32, Using TImage32


TImgView32

Hierarchy

TCustomControl

|

TCustomPaintBox32

|

TCustomImage32

|

TCustomImgView32

Description

An image displaying control with scroll bars.

TImgView32 implements the generic behavior introduced in TCustomImgView32. It publishes some inherited properties from TCustomImgView32, but does not introduce any new behavior.

Reference

Methods | Properties | Events
In TCustomImgView32:
Create | Centered | OnScroll
Destroy | OverSize |
GetViewportRect | ScrollBars |
Loaded | SizeGrip |
Resize |  |
Scroll |  |
ScrollToCenter |  |
In TCustomImage32:
BeginUpdate | Bitmap | OnBitmapResize
BitmapToControl | BitmapAlign | OnChange
Changed | Layers | OnGDIOverlay
ControlToBitmap | OffsetHorz | OnInitStages
EndUpdate | OffsetVert | OnMouseDown
ExecBitmapFrame | PaintStages | OnMouseMove
ExecClearBackgnd | Scale | OnMouseUp
ExecClearBuffer | ScaleMode | OnPaintStage
ExecControlFrame | ScaleX | OnPixelCombine
ExecCustom | ScaleY | OnScaleChange
ExecDrawBitmap |  |
ExecDrawLayers |  |
GetPictureRect |  |
GetPictureSize |  |
SetupBitmap |  |
In TCustomPaintBox32:
DoPaintBuffer | Buffer | OnMouseEnter
Flush | BufferOversize | OnMouseLeave
ForceFullInvalidate | BufferValid |
Invalidate | Options |
SetBounds | RepaintMode |

See Also

TCustomImgView32


TIVScrollProperties

Hierarchy

TPersistent

Description

TIVScrollProperties is an auxiliary class for accessing properties of scroll bars (TCustomRangeBar controls) that are hosted by the TCustomImgView32 control. Basically, it just redirects writing and reading of properties to/from corresponding range bar controls, which allows changing their appearance at both design- and run-time.

Reference

Fields | Properties
In TIVScrollProperties:
 | Backgnd
 | BorderStyle
 | ButtonSize
 | HandleColor
 | Increment
 | ShowArrows
 | ShowHandleGrip
 | Size
 | Style
 | Visibility

See Also

TCustomImgView32.ScrollBars, TCustomImgView32, TCustomRangeBar


Backgnd

TIVScrollProperties.Backgnd

property Backgnd: TRBBackgnd;

type TRBBackgnd = (bgPattern, bgSolid);

Description

Provides access to the Backgnd property in scroll bars.

See Also

TArrowBar.Backgnd, TRBBackgnd


BorderStyle

TIVScrollProperties.BorderStyle

property BorderStyle: TBorderStyle;
type TBorderStyle = (bsNone, bsSingle); // is declared in Forms.pas

Description

Provides access to the BorderStyle property in scroll bars.

See Also

TArrowBar.BorderStyle


ButtonSize

TIVScrollProperties.ButtonSize

property ButtonSize: Integer;

Description

Provides access to the ButtonSize property in scroll bars.

See Also

TArrowBar.ButtonSize


HandleColor

TIVScrollProperties.HandleColor

property HandleColor: TColor;

Description

Provides access to the HandleColor property in scroll bars.

See Also

TArrowBar.HandleColor


Increment

TIVScrollProperties.Increment

property Increment: Integer;

Description

Provides access to the Increment property in scroll bars.

See Also

TCustomRangeBar.Increment


ShowArrows

TIVScrollProperties.ShowArrows

property ShowArrows: Boolean;

Description

Provides access to the ShowArrows property in scroll bars.

See Also

ShowArrows


ShowHandleGrip

TIVScrollProperties.ShowHandleGrip

property ShowHandleGrip: Boolean;

Description

Provides access to the ShowHandleGrip property in scroll bars.

See Also

TArrowBar.ShowHandleGrip


Size

TIVScrollProperties.Size

property Size: Integer;

Description

Simultaneously controls the Height of horizontal and Width of veritical scroll bars.

If Size is 0 (default), the corresponding size is set to the default one, specified in current desktop settings.


Style

TIVScrollProperties.Style

property Style: TRBStyle;

Description

Provides access to the Style property in scroll bars.

See Also

TArrowBar.Style, TRBStyle


Visibility

TIVScrollProperties.Visibility

property Visibility: TScrollbarVisibility;

type TScrollBarVisibility = (svAlways, svHidden, svAuto);

Description

Controls the visibility of the scrollbars.

svAlways will always display the scrollbars;

svHidden will always hide the scrollbars;

svAuto will only show the scrollbars if the (scaled) workspace does not completely fit into the current viewport.


TPaintBox32

Hierarchy

TCustomControl

|

TCustomPaintBox32

Description

TPaintBox32 implements the generic behavior introduced in TCustomPaintBox32. It publishes some inherited properties from its ancestors and, in addition, it calls the OnPaintBuffer event when the buffer needs to be repainted.

Reference

Fields | Methods | Properties | Events
In TPaintBox32:
 | Create |  | OnPaintBuffer
 | DoPaintBuffer |  |
 | Flush |  |
In TCustomPaintBox32:
 | Destroy | Buffer | OnMouseEnter
 | ForceFullInvalidate | BufferOversize | OnMouseLeave
 | GetViewportRect | BufferValid |
 | Invalidate | Options |
 | Loaded | RepaintMode |
 | Resize |  |
 | SetBounds |  |

See Also

TCustomPaintBox32


Create

TPaintBox32.Create

constructor Create(AOwner: TComponent);

Description

Creates an instance of TPaintBox32.

See Also

TPaintBox32


DoPaintBuffer

TPaintBox32.DoPaintBuffer

procedure DoPaintBuffer; override; // protected

Description

This method is overriden from TCustomPaintBox32, it calls the OnPaintBuffer event.

See Also

TCustomPaintBox32.DoPaintBuffer, OnPaintBuffer, TCustomPaintBox32


Flush

TPaintBox32.Flush

procedure Flush; overload;

procedure Flush(const SrcRect: TRect); overload;

Description

Immediately copies the contents of the buffer, or its part passed in SrcRect to the screen. Use this function when you want to bypass normal Windows invalidating/repainting procedure, for example when the buffer is painted by the other thread.

Both functions are thread-safe.

See Also

Rectangle Types


OnPaintBuffer

TPaintBox32.OnPaintBuffer

property OnPaintBuffer: TNotifyEvent;

Description

OnChange is called by TPaintBox32 when it needs to repaint its back buffer itself.

See Also

TCustomPaintBox32.Buffer, DoPaintBuffer, TCustomPaintBox32


TPaintStages

Hierarchy

TObject

Description

A dynamic list of paint stages.

This class is similar to standard TList, but instead of pointers, it holds an array of TPaintStage records.

Reference

Fields | Methods | Properties
In TPaintStages:
 | Add | Items
 | Clear |
 | Count |
 | Delete |
 | Destroy |
 | Insert |

See Also

Paint Stages, TCustomImage32.PaintStages, TPaintStage


Add

TPaintStages.Add

function Add: PPaintStage;

Description

Adds a new stage to the list and returns pointer to stage record.

By default, new stages have their RunTime member set to True.

See Also

Delete, Insert, TPaintStage


Clear

TPaintStages.Clear

procedure Clear;

Description

Removes all stages from the list.

See Also

Delete


Count

TPaintStages.Count

function Count: Integer;

Description

Returns the number of stored stages.


Delete

TPaintStages.Delete

procedure Delete(Index: Integer);

Description

Removes the stage at the position specified by the Index parameter. The index of subsequent stages automatically decreases.

See Also

Add, Insert


Destroy

TPaintStages.Destroy

destructor Destroy; override;

Description

Destroys an instance of TPaintStages object and frees the memory allocated to stare the list of stages.

Do not call Destroy directly, call the standard Free method instead.

See Also

TPaintStages


Insert

TPaintStages.Insert

function Insert(Index: Integer): PPaintStage;

Description

Insert a new stage into the list at specified position and returns a pointer to it.

Index indicates the position, where the new stage is inserted. The item that occupied that position before insertion, is shifted up together with all subsequent items.

If Index is greater than the number of stages, the new stage will be added at the end of the list. Similarly, if Index is less or equal than zero, all previous elements are shifted up and the new stage is inserted in the beginning of the list.

By default, new stages have their RunTime member set to True.

See Also

Add, Delete, TPaintStage


Items

TPaintStages.Items

property Items[Index: Integer]: PPaintStage; default; // Read only;

Description

The Items property can be used to obtain a pointer to the specified stage. The index of the first paint stage is 0.

See Also

TPaintStage


GR32_Layers

The GR32_Layers.pas unit contains layer classes, which can be attached to TCustomImage32 class and its descendants.

Contents

Types | Classes | Constants
TRBHandles | TBitmapLayer | Layer Options Bits
TRBOptions | TCustomLayer |
 | TLayerCollection |
 | TPositionedLayer |
 | TRubberbandLayer |

See Also

Examples, TCustomImage32, Using Layers


TRBHandles

type TRBHandles = set of (rhCenter, rhSides, rhCorners, rhFrame,
rhNotLeftSide, rhNotRightSide, rhNotTopSide, rhNotBottomSide,
rhNotTLCorner, rhNotTRCorner, rhNotBLCorner, rhNotBRCorner);

Description

The type of the Handles property in TRubberbandLayer.

See Also

TRubberbandLayer.Handles, TRubberbandLayer


TRBOptions

type TRBOptions = set of (roConstrained, roProportional);

Description

The type of the Options property in TRubberbandLayer.

See Also

TRubberbandLayer.Options, TRubberbandLayer


Layer Options Bits

The basic behavior of the layer is controlled by its LayerOptions property, an unsigned 32-bit integer field of bits. The upper 8 bits in this field are reserved for default options:

Bit # | Constant Name | Description
31 | LOB_VISIBLE | Controls the layer visibility
30 | LOB_GDI_OVERLAY | Indicates that the layer performs drawing when its owner (TCustomImage32 control or its descendant) draws its GDI Overlays. [ Note: Most likely, this constant will not be used in future versions. Do not use it ]
29 | LOB_MOUSE_EVENTS | Specifies whether the layer responds to mouse messages.
28 | LOB_NO_UPDATE | Disables automatic repainting when the layer changes its location or other properties.
27 | LOB_NO_CAPTURE | Allows to override automatic capturing of mouse messages when the left mouse is pressed on top of the layer. This bit has no effect if LOB_MOUSE_EVENTS is not set.
26 | LOB_RESERVED_26 | Reserved for future use
25 | LOB_RESERVED_25 | Reserved for future use
24 | LOB_RESERVED_24 | Reserved for future use

Other 24 bits can be used for any other purpose, as customized layer classification etc.

See Also

TCustomLayer.LayerOptions


TBitmapLayer

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomLayer

|

TPositionedLayer

Description

In addition to behavior inherited from TPositionedLayer, TBitmapLayer, stores and displays a TBitmap32 object.

The contained Bitmap is displayed and scaled using its DrawMode, MasterAlpha and StretchFilter properties.

Reference

Fields | Methods | Properties | Events
In TBitmapLayer:
 | Create | AlphaHit |
 | Destroy | Bitmap |
 |  | Cropped |
In TPositionedLayer:
 | GetAdjustedLocation | Location |
 | GetAdjustedRect | Scaled |
In TCustomLayer:
 | BringToFront | Cursor | OnHitTest
 | Changed | Index | OnMouseDown
 | HitTest | LayerCollection | OnMouseMove
 | SendToBack | LayerOptions | OnMouseUp
 | Update | LayerStates | OnPaint
 |  | MouseEvents |
 |  | Tag |
 |  | Visible |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | EndUpdate |  |

See Also

TCustomBitmap32.DrawMode, TCustomBitmap32.MasterAlpha, Examples, TCustomBitmap32.StretchFilter, TBitmap32, TPositionedLayer


Create

TBitmapLayer.Create

constructor Create(ALayerCollection: TLayerCollection); override;

Description

Creates an instance of TBitmapLayer.

After calling the inherited constructor, Create initializes the internal bitmap and returns an object with both AlphaHit and Cropped properties set to False.

See Also

AlphaHit, TCustomLayer.Create, Cropped, TBitmapLayer, TLayerCollection


Destroy

TBitmapLayer.Destroy

destructor Destroy; override;

Description

Removes the bitmap layer from the collection and destroys it. The memory allocated for the bitmap is freed as well.

Do not call Destroy in your application directly, use the standard Free method instead.


AlphaHit

TBitmapLayer.AlphaHit

property AlphaHit: Boolean;

Description

AlphaHit determines how the layer performs its HitTest.

If AlphaHit=False, layer only passes points inside the rectangle returned by GetAdjustedLocation.

If AlphaHit=True, layer checks the opacity of the pixel lying under the specified point and passes the hit test only when the alpha channel of the pixel is greater when zero.

See Also

TPositionedLayer.GetAdjustedLocation, TCustomLayer.HitTest


Bitmap

TBitmapLayer.Bitmap

property Bitmap: TBitmap32;

Description

Specifies the contained image.

See Also

TBitmap32


Cropped

TBitmapLayer.Cropped

property Cropped: Boolean;

Description

When Cropped is True, layer will paint only the portion of its bitmap, that intersects with the bitmap image of the container:

See Also

Bitmap Image


TCustomLayer

Hierarchy

TPersistent

|

TNotifiablePersistent

Description

TCustomLayer is the base class for all layers. It does not perform any drawing itself. Instead it calls an OnPaint event. Applications must provide a handler for this event in order to paint the layer.

Reference

Fields | Methods | Properties | Events
In TCustomLayer:
 | BringToFront | Cursor | OnHitTest
 | Changed | Index | OnMouseDown
 | Create | LayerCollection | OnMouseMove
 | Destroy | LayerOptions | OnMouseUp
 | HitTest | LayerStates | OnPaint
 | SendToBack | MouseEvents |
 | Update | Tag |
 |  | Visible |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | EndUpdate |  |

See Also

TCustomLayer, Using Layers


BringToFront

TCustomLayer.BringToFront

procedure BringToFront;

Description

Makes the layer the top-most layer of the layer collection it belongs to. After calling BringToFront, the layer's Index value is the highest among the layers in the same layer collection.

See Also

Index, LayerCollection, Using Layers


Changed

TCustomLayer.Changed

procedure Changed;

procedure Changed(const Rect: TRect);

Description

Will mark the layer for update and calls the OnChange event, provided the change notification is not masked with BeginUpdate. If a rectangle of the changed area (Rect) is set, only this area will be updated - provided the RepaintMode of the owning TCustomImage32 instance is set to rmOptimizer.

See Also

TNotifiablePersistent.BeginUpdate, TNotifiablePersistent.OnChange, TLayerCollection.Owner, TCustomPaintBox32.RepaintMode, TCustomImage32, Rectangle Types, TRepaintMode, Update, Using Layers


Create

TCustomLayer.Create

constructor Create(ALayerCollection: TLayerCollection); virtual;

Description

Creates a new instance of TCustomLayer and adds it to the specified layer collection.

By default, new layers are created with only the LOB_VISIBLE bit set in their LayerOptions.

See Also

LayerOptions, TCustomLayer, TLayerCollection, Using Layers


Destroy

TCustomLayer.Destroy

destructor Destroy; override;

Description

Removes the layer from its layer collection, destroys the layer instance, and frees all allocated memory.

Do not call Destroy directly. Instead, use the Free method which verifies that the layer reference is assigned and only than calls Destroy.

See Also

LayerCollection, Using Layers


HitTest

TCustomLayer.HitTest

function HitTest(X, Y: Integer): Boolean;

Description

Performs a hit test of the layer at specified point and returns True if the point have passed the test.

After performing default hit test, specific for particular type of a layer, this method also calls OnHitTest event, in case you need some run-time customization.

By default:

  • TCustomLayer always passes the hit test;
  • TPositionedLayer passes only the points lying inside the rectangle, returned by GetAdjustedLocation;
  • Depending on the AlphaHit property, TBitmapLayer is capable of passing only coordinates corresponding to non-transparent pixels.

See Also

TBitmapLayer.AlphaHit, TPositionedLayer.GetAdjustedLocation, OnHitTest, TBitmapLayer, TCustomLayer, TPositionedLayer, Using Layers


SendToBack

TCustomLayer.SendToBack

procedure SendToBack;

Description

Makes the layer the background layer of the layer collection it belongs to. Calling SendToBack has the same effect as setting the layer's Index value to 0.

See Also

Index, LayerCollection, Using Layers


Update

TCustomLayer.Update

procedure Update;

procedure Update(const Rect: TRect);

Description

Update will mark the layer for a repaint. If a rectangle of the changed area (Rect) is set, only this area will be repainted - provided the RepaintMode of the owning TCustomImage32 instance is set to rmOptimizer.

See Also

Changed, TLayerCollection.Owner, TCustomPaintBox32.RepaintMode, TCustomImage32, Rectangle Types, TRepaintMode, Using Layers


Cursor

TCustomLayer.Cursor

property Cursor: TCursor;

Description

Specifies the appearance of the mouse pointer, when it passes over the region covered by the layer. Whether this property used or not is influenced by LOB_MOUSE_EVENTS bit in LayerOptions, as well as by the hit test.

See Also

LayerOptions, Using Layers


Index

TCustomLayer.Index

property Index: Integer;

Description

Indicates the position of the layer in the LayerCollection to which it belongs. The background layer has an Index value of 0, the layer directly on to of the background layer has an Index value of 1, and so forth. Change Index to reorder the layers in a LayerCollection.

See Also

LayerCollection, Using Layers


LayerCollection

TCustomLayer.LayerCollection

property LayerCollection: TLayerCollection;

Description

Points to the LayerCollection, to which the layer belongs.

See Also

TLayerCollection, Using Layers


LayerOptions

TCustomLayer.LayerOptions

property LayerOptions: Cardinal;

Description

A 32-bit unsigned integer value composed of Layer Options Bits, which controls the layer's behavior.

Note that the lower 24-bits of LayerOptions have no predefined meaning; they are available for customization purposes, like layer categories, etc.

See Also

Layer Options Bits, Using Layers


LayerStates

TCustomLayer.LayerStates

property LayerStates: TLayerStates; // Read only

type TLayerState = (lsMouseLeft, lsMouseRight, lsMouseMiddle);

type TLayerStates = set of TLayerState;

Description

Indicates the current state of the layer. At the moment, this property contains only information on pressed mouse buttons, but it will be expanded in future versions.

See Also

Using Layers


MouseEvents

TCustomLayer.MouseEvents

property MouseEvents: Boolean;

Description

Returns True if the LOB_MOUSE_EVENTS bit in LayerOptions is set; otherwise False is returned. Setting MouseEvents changes the LOB_MOUSE_EVENTS bit in LayerOptions accordingly.

See Also

Layer Options Bits, LayerOptions, Using Layers


Tag

TCustomLayer.Tag

property Tag: Integer;

Description

Tag has no predefined meaning, it can be used to store any 32-bit value as part of the layer.

See Also

Using Layers


Visible

TCustomLayer.Visible

property Visible: Boolean;

Description

Returns True if the LOB_VISIBLE bit in LayerOptions is set; otherwise False is returned. Setting Visible changes the LOB_VISIBLE bit in LayerOptions accordingly.

See Also

Layer Options Bits, LayerOptions, Using Layers


OnHitTest

TCustomLayer.OnHitTest

property OnHitTest: THitTestEvent;

type THitTestEvent = procedure(Sender: TObject; X, Y: Integer; var Passed: Boolean) of object;

Description

Provide a handler for this event to customize the mouse hit testing. The X and Y parameters indicate the mouse position relative to TCustomImage32 (or its descendant) top-left corner.

See Also

TCustomImage32, Using Layers


OnMouseDown

TCustomLayer.OnMouseDown

property OnMouseDown: TMouseEvent;

type TMouseEvent = procedure (Sender: TObject; Button: TMouseButton ; Shift: TShiftState; X, Y: Integer) of object;

Description

This event is obsolete and remains here only for backward compatibility. Use the OnMouseDown event of TCustomImage32 instead.

[See also]: Using Layers, OnMouseMove, OnMouseUp

See Also

TCustomImage32.OnMouseDown, OnMouseMove, OnMouseUp, TCustomImage32, Using Layers


OnMouseMove

TCustomLayer.OnMouseMove

property OnMouseMove: TMouseMoveEvent;

type TMouseMoveEvent = procedure(Sender: TObject; Shift: TShiftState; X, Y: Integer) of object;

Description

This event is obsolete and remains here only for backward compatibility. Use the OnMouseMove event of TCustomImage32 instead.

See Also

OnMouseDown, TCustomImage32.OnMouseMove, OnMouseUp, TCustomImage32, Using Layers


OnMouseUp

TCustomLayer.OnMouseUp

property OnMouseUp: TMouseEvent;

type TMouseEvent = procedure (Sender: TObject; Button: TMouseButton ; Shift: TShiftState; X, Y: Integer) of object;

Description

This event is obsolete and remains here only for backward compatibility. Use the OnMouseUp event of TCustomImage32 instead.

See Also

OnMouseMove, TCustomImage32.OnMouseUp, TCustomImage32, Using Layers


OnPaint

TCustomLayer.OnPaint

property OnPaint: TPaintLayerEvent;

type TPaintLayerEvent = procedure(Sender: TObject; Buffer: TBitmap32) of object;

Description

Provide a handler for this event to paint the layer. Use the TBitmap32 instance indicated by the Buffer parameter to paint the layer.

See Also

TBitmap32, Using Layers


TLayerCollection

Hierarchy

TPersistent

Description

TLayerCollection is a container for TCustomLayer objects and their descendants.

Reference

Fields | Methods | Properties
In TLayerCollection:
 | Add | Count
 | Clear | GetViewportScale
 | Create | GetViewportShift
 | Delete | Items
 | Destroy | LocalToViewport
 | Insert | MouseEvents
 |  | MouseListener
 |  | Owner
 |  | ViewportToLocal

See Also

TCustomLayer, Using Layers


Add

TLayerCollection.Add

function Add(ItemClass: TLayerClass): TCustomLayer;

type TLayerClass = class of TCustomLayer;

Description

Adds a new layer to the collection. The layer is added to the end of the list and it's Index property will become equal to Count - 1.

The class of the layer is specified in the ItemClass parameter and you will need to typecast the result to ItemClass if you need to access its specific properties, for example:

var

BL: TBitmapLayer;

begin

BL := TBitmapLayer(MyImage32.Layers.Add(TBitmapLayer));

...

end;

Alternatively, you can use another approach to add layers to the collection:

var

BL: TBitmapLayer;

begin

BL := TBitmapLayer.Create(MyImage32.Layers);

end;

See Also

Count, TCustomLayer.Index, TCustomLayer, Using Layers


Clear

TLayerCollection.Clear

procedure Clear;

Description

Removes and destroys all the layers from the collection.

See Also

Using Layers


Create

TLayerCollection.Create

constructor Create(AOwner: TPersistent);

Description

Creates a new instance of TLayerCollection. This constructor is used internally in constructor of TCustomImage32 to initialize its Layers property.

See Also

TCustomImage32.Layers, TCustomImage32, TLayerCollection, Using Layers


Delete

TLayerCollection.Delete

procedure Delete(Index: Integer);

Description

Removes and destroy the layer with specified index from the collection.

See Also

Using Layers


Destroy

TLayerCollection.Destroy

destructor Destroy; override;

Description

Destroys an instance of TLayerCollection together with all contained layers. This destructor is used in the destructor of TCustomImage32 to property deallocate its Layers property.

See Also

TCustomImage32.Layers, TCustomImage32, TLayerCollection, Using Layers


Insert

TLayerCollection.Insert

function Insert(Index: Integer; ItemClass: TLayerClass): TCustomLayer;

type TLayerClass = class of TCustomLayer;

Description

Inserts a new layer at the specified position. Insert works similar to the Add method.

See Also

Add, TCustomLayer, Using Layers


Count

TLayerCollection.Count

property Count: Integer; // Read only

Description

Indicates the amount of layers stored in the collection.

See Also

Items, Using Layers


GetViewportScale

TLayerCollection.GetViewportScale

procedure GetViewportScale(var ScaleX, ScaleY: Single);

Description

Returns the X and Y scale of the viewport. In the default implementation this equals the ScaleX and ScaleY property of the connected TCustomImage32 descendant.

Note: If you previously used CoordXForm property (now removed), use GetViewportScale instead to retrieve the viewport scale.

See Also

TCustomImage32.ScaleX, TCustomImage32.ScaleY, TCustomImage32, Using Layers


GetViewportShift

TLayerCollection.GetViewportShift

procedure GetViewportShift(var ShiftX, ShiftY: Single);

Description

Returns the X and Y shift of the viewport.

Note: If you previously used CoordXForm property (now removed), use GetViewportShift instead to retrieve the viewport shift.

See Also

Using Layers


Items

TLayerCollection.Items

property Items[Index: Integer]: TCustomLayer;

Description

Provides indexed access to contained layers. Index of layers is zero-based.

See Also

Count, TCustomLayer, Using Layers


LocalToViewport

TLayerCollection.LocalToViewport

function LocalToViewport(const APoint: TFloatPoint; AScaled: Boolean): TFloatPoint;

Description

Transforms a given point (APoint) from the local coordinate system to the viewport's coordinate system and returns the result. If AScaled is False the output is equal to the input point.

See Also

Using Layers


MouseEvents

TLayerCollection.MouseEvents

property MouseEvents: Boolean;

Description

Determines if mouse messages from the owner (TCustomImage32) do propagate to layers.

See Also

TCustomImage32, Using Layers


MouseListener

TLayerCollection.MouseListener

property MouseListener: TCustomLayer;

Description

Indicates the layer which has captured mouse messages. By default, the layer captures mouse if the left mouse button is pressed and releases it when the mouse button is released.

Note, that since layers have nothing to do with windowed controls, this property is just a simulation of standard mouse capturing. Windows still 'thinks' that the mouse is captured to the owner of the layer collection (TCustomImage32), which in turn redirects mouse messages to an appropriate layer.

See Also

TCustomImage32, TCustomLayer, Using Layers


Owner

TLayerCollection.Owner

property Owner: TPersistent;

Description

Indicates the owner of the layer collection. Usually the owner is the displaying control like TCustomImage32 or TCustomImgView32.

See Also

TCustomImage32, TCustomImgView32, Using Layers


ViewportToLocal

TLayerCollection.ViewportToLocal

function ViewportToLocal(const APoint: TFloatPoint; AScaled: Boolean): TFloatPoint;

Description

Transforms a given point (APoint) from the viewport's coordinate system to the local coordinate system and returns the result. If AScaled is False the output is equal to the input point.

See Also

Using Layers


TPositionedLayer

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomLayer

Description

TPositionedLayer is the base class for layers that are positioned withing the boundaries of their container (TCustomImage32 or its descendant). The position and size is determined by the Location property.

When TPositionedLayer performs its HitTest, those points inside the rectangle returned by GetAdjustedLocation pass the test.

The class does not perform any drawing itself, however it is capable of calling the OnPaint event, where you can perform cutom drawing.

Reference

Fields | Methods | Properties | Events
In TPositionedLayer:
 | Create | Location |
 | GetAdjustedLocation | Scaled |
 | GetAdjustedRect |  |
In TCustomLayer:
 | BringToFront | Cursor | OnHitTest
 | Changed | Index | OnMouseDown
 | Destroy | LayerCollection | OnMouseMove
 | HitTest | LayerOptions | OnMouseUp
 | SendToBack | LayerStates | OnPaint
 | Update | MouseEvents |
 |  | Tag |
 |  | Visible |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | EndUpdate |  |

See Also

TCustomImage32, Using Layers


Create

TPositionedLayer.Create

constructor Create(ALayerCollection: TLayerCollection); override;

Description

Creates the instance of TPositionedLayer.

After calling the inherited constructor, Create initializes the following properties:

  • LayerOptions to LOB_VISIBLE or LOB_MOUSE_EVENTS;
  • Scaled to False;
  • Location to FloatRect(0, 0, 64, 64);

See Also

TCustomLayer.Create, TCustomLayer.LayerOptions, Location, Scaled, TLayerCollection, TPositionedLayer, Using Layers


GetAdjustedLocation

TPositionedLayer.GetAdjustedLocation

function GetAdjustedLocation: TFloatRect;

Description

When the Scaled property is True, GetAdjustedLocation returns scaled Location, otherwise it returns Location as it is, without scaling.

It is up to you do decide if you want to use the result as a floating-point rectangle, to round the coordinates before painting:

procedure TForm1.OnLayerPaintHandler(Sender: TObject; Buffer: TBitmap32);

var

R: TRect;

begin

if Sender is TPositionedLayer then

with TPositionedLayer(Sender) do

begin

R := MakeRect(GetAdjustedLocation);

Buffer.FrameRectS(R.Left, R.Top, R.Right, R.Bottom, clRed32);

end;

end;

end;

See Also

GetAdjustedRect, Location, Scaled, Rectangle Types, Using Layers


GetAdjustedRect

TPositionedLayer.GetAdjustedRect

function GetAdjustedRect(const R: TFloatRect): TFloatRect;

Description

When the Scaled property is True, GetAdjustedRect returns the scaled version of the input rect (R), otherwise it returns R as it is, without scaling.

See Also

GetAdjustedLocation, Scaled, Rectangle Types, Using Layers


Location

TPositionedLayer.Location

property Location: TFloatRect;

Description

Determines layer's position and size.

Note, that the layer is not constrained to lie entirely within the rectangle specified by Location. It may perform drawing outside the Location and may catch mouse messages from other areas.

When the layer is Scaled, its actual location its position after scaling may be obtained through GetAdjustedLocation method.

See Also

GetAdjustedLocation, Scaled, Rectangle Types, Using Layers


Scaled

TPositionedLayer.Scaled

property Scaled: Boolean;

Description

Specifies if the layer is scaled and determines the result returned by GetAdjustedLocation. When set to True, scaling is influenced by the layout of bitmap image in the container (TCustomImage32 object or its descendant).

See Also

Bitmap Image, GetAdjustedLocation, TCustomImage32, Using Layers


TRubberbandLayer

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomLayer

|

TPositionedLayer

Description

This class implements a rubber band, allowing to move and resize other positioned layers at run-time. The layer paints itself at GDI Overlays stage, using the standard GDI methods.

It is a good idea to keep TRubberbandLayer on top of other layers so that thay don't intercept mouse messages.

Note, that this is a preliminary implementation of rubber banding, there is a lot to be done here to make its behavior more consistent, which will be done in future versions of the library. However, most likely I will keep names and general meaning of most properties and methods.

Reference

Fields | Methods | Properties | Events
In TRubberbandLayer:
 | Create | ChildLayer | OnConstrain
 | Destroy | FrameStippleCounter | OnResizing
 | SetFrameStipple | FrameStippleStep | OnUserChange
 |  | HandleFill |
 |  | HandleFrame |
 |  | Handles |
 |  | HandleSize |
 |  | MaxHeight |
 |  | MaxWidth |
 |  | MinHeight |
 |  | MinWidth |
 |  | Options |
In TPositionedLayer:
 | GetAdjustedLocation | Location |
 | GetAdjustedRect | Scaled |
In TCustomLayer:
 | BringToFront | Cursor | OnHitTest
 | Changed | Index | OnMouseDown
 | HitTest | LayerCollection | OnMouseMove
 | SendToBack | LayerOptions | OnMouseUp
 | Update | LayerStates | OnPaint
 |  | MouseEvents |
 |  | Tag |
 |  | Visible |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | EndUpdate |  |

See Also

Paint Stages, Using Layers


Create

TRubberbandLayer.Create

constructor Create(ALayerCollection: TLayerCollection); override;

Description

Creates an instance of TRubberbandLayer and adds it into the specified collection.

See Also

TCustomLayer.Create, TLayerCollection, TRubberbandLayer


Destroy

TRubberbandLayer.Destroy

destructor Destroy; override;

Description

Removes the rubber band layer from the collection and destroys it .

Do not call Destroy directly in your application, use the standard Free method instead.


SetFrameStipple

TRubberbandLayer.SetFrameStipple

procedure SetFrameStipple(const Value: Array of TColor32);

Description

Sets the stipple pattern for the frame in the rubberband.

See Also

Color Types, FrameStippleStep


ChildLayer

TRubberbandLayer.ChildLayer

property ChildLayer: TPositionedLayer;

Description

Points to the position layer, controlled by the rubber band. TRubberbandLayer will keep Location of its child layer the same as its own Location.

See Also

TPositionedLayer.Location, TPositionedLayer, TRubberbandLayer


FrameStippleCounter

TRubberbandLayer.FrameStippleCounter

property FrameStippleCounter: Single;

Description

Specifies the current position of the stipple pattern of the surrounding frame.

Hint: By using a timer and modifying the FrameStippleCounter, it is possible to animate the frame of the rubberband.

See Also

SetFrameStipple


FrameStippleStep

TRubberbandLayer.FrameStippleStep

property FrameStippleStep: Single;

Description

Specifies the stepping for the stipple pattern of the surrounding frame.

See Also

SetFrameStipple


HandleFill

TRubberbandLayer.HandleFill

property HandleFill: TColor32;

Description

Specifies the color of the drag handle.


HandleFrame

TRubberbandLayer.HandleFrame

property HandleFrame: TColor32;

Description

Specifies the frame color of the drag handle.


Handles

TRubberbandLayer.Handles

property Handles: TRBHandles;

type TRBHandles = set of (rhCenter, rhSides, rhCorners, rhFrame,
rhNotLeftSide, rhNotRightSide, rhNotTopSide, rhNotBottomSide,
rhNotTLCorner, rhNotTRCorner, rhNotBLCorner, rhNotBRCorner);

Description

Determines which handles are visible and draggable by the mouse.

  • rhCenter – corresponds to the internal area of the control, that is the area inside the rectangle specified by Location;
  • rhSides – corresponds to the handles on the edges of the layer;
  • rhCorners – corresponds to the handles at the corners of the layer;
  • rhFrame - corresponds to the frame surrounding the layer;
  • rhNotLeftSide, rhNotRightSide, rhNotTopSide, rhNotBottomSide - set to disable one or more sides (needs rhSides);
  • rhNotTLCorner, rhNotTRCorner, rhNotBLCorner, rhNotBRCorner - set to disable one or more corners (needs rhCorners);

See Also

TPositionedLayer.Location, TRBHandles


HandleSize

TRubberbandLayer.HandleSize

property HandleSize: Integer;

Description

Determines the size of the handles. The actual size in pixels may be calculated as

HandleSize * 2 + 1


MaxHeight

TRubberbandLayer.MaxHeight

property MaxHeight: Single;

Description

Determines the maximum height of the rubber band while it resizes. When MaxHeight is less than or equal to MinHeight, this property is disregarded and the maximum height becomes unlimited.

See Also

MaxWidth, MinHeight


MaxWidth

TRubberbandLayer.MaxWidth

property MaxWidth: Single;

Description

Determines the maximum width of the rubber band while it resizes. When MaxWidth is less than or equal to MinWidth, this property is disregarded and the maximum width becomes unlimited.

See Also

MinWidth


MinHeight

TRubberbandLayer.MinHeight

property MinHeight: Single;

Description

Determines the minimum height of the rubber band while it resizes.

See Also

MinWidth


MinWidth

TRubberbandLayer.MinWidth

property MinWidth: Single;

Description

Determines the minimum width of the rubber band while it resizes.

See Also

MinHeight


Options

TRubberbandLayer.Options

property Options: TRBOptions;

type TRBOptions = set of (roConstrained, roProportional);

Description

Determines how the rubber band layer shall behave when being modified:

  • roConstrained – enables calling of the OnConstrain event to constrain the size and position of the layer to a given maximum or minimum;
  • roProportional – defines that the rubber band layer shall only resize proportionally, ie. keeping the aspect ratio.

See Also

OnConstrain, TRBOptions


OnConstrain

TRubberbandLayer.OnConstrain

property OnConstrain: TRBConstrainEvent;

type TRBConstrainEvent = procedure(
Sender: TObject;
const OldLocation: TFloatRect;
var NewLocation: TFloatRect;
DragState: TDragState;
Shift: TShiftState) of object;

type TDragState = (dsNone, dsMove, dsSizeL, dsSizeT, dsSizeR, dsSizeB, dsSizeTL, dsSizeTR, dsSizeBL, dsSizeBR);

Description

When Options contains roConstrained the OnConstrain event allows for constraining the size and position of the rubber band while it is being moved or resized using the mouse. This event is called only when the user clicks and drags the layer with the mouse, it is not generated when you set the Location property explicitly. It is called before OnResizing and proportional resizing (roProportional in Options).

OldLocation specifies location of the layer before the user started dragging it.

NewLocation determines the new location of the rubber band. You may change the coordinates to constrain to a certain given maximum or minimum.

The DragState parameter indicates how the layer is being dragged/resized.

Shift indicates the state of the Alt, Ctrl, and Shift keys.

See Also

TPositionedLayer.Location, OnResizing, Options


OnResizing

TRubberbandLayer.OnResizing

property OnResizing: TRBResizingEvent;

type TRBResizingEvent = procedure(
Sender: TObject;
const OldLocation: TFloatRect;
var NewLocation: TFloatRect;
DragState: TDragState;
Shift: TShiftState) of object;

type TDragState = (dsNone, dsMove, dsSizeL, dsSizeT, dsSizeR, dsSizeB, dsSizeTL, dsSizeTR, dsSizeBL, dsSizeBR);

Description

OnResizing allows for runtime customization of the rubber band which is being moved or resized using the mouse. This event is called only when the user clicks and drags the layer with the mouse, it is not generated when you set the Location property explicitly.

OldLocation specifies location of the layer before the user started dragging it.

NewLocation determines the new location of the rubber band. You may change the coordinates in order to provide required response to dragging or resizing operation.

The DragState parameter indicates how the layer is being dragged/resized.

Shift indicates the state of the Alt, Ctrl, and Shift keys.

See Also

TPositionedLayer.Location


OnUserChange

TRubberbandLayer.OnUserChange

property OnUserChange: TNotifyEvent;

Description

The event is called automatically when the layer is moved or resized with the mouse. OnUserChange is not colled when you change Location explicitly.

See Also

TPositionedLayer.Location


GR32_Lowlevel

GR32_Lowlevel.pas is a collection of RTL extensions and auxiliary low level routines. The unit is primarily used internally in Graphics32.

Contents

Types | Routines
Wrap Procedure Types | Clamp
 | Colorswap
 | Constrain
 | FillLongword
 | FillWord
 | Mirror
 | MoveLongword
 | MoveWord
 | Shift Arithmetic Right
 | Swap
 | SwapConstrain
 | TestClip
 | TestSwap
 | Wrap


Wrap Procedure Types

type
TWrapProc = function (Value, Max: Integer): Integer;
TWrapProcEx = function (Value, Min, Max: Integer): Integer;

Desctiption

These function types are used in relation to wrapmodes. While TWrapProc implicitly uses zero as minimum value, TWrapProcEx lets the caller define the complete minimum to maximum range.


Clamp

function Clamp(const Value: Integer): TColor32; overload;

function Clamp(Value: Integer; Max: Integer): Integer; overload;

function Clamp(Value: Integer; Min: Integer; Max: Integer): Integer; overload;

Description

First version restricts Value to [0..255] range.

Second version restricts Value to [0..Max] range.

Third version restricts Value to [Min..Max] range.

This function is used in TWrapMode wmClamp.

See Also

Mirror, TWrapMode, Wrap


Colorswap

function ColorSwap(WinColor: TColor): TColor32;

Description

ColorSwap exchanges ARGB <-> ABGR and fills A with $FF

See Also

Color Types


Constrain

function Constrain(const Value: Integer; const Lo: Integer; const Hi: Integer): Integer;

Description

Returns Value constrained to [Lo..Hi] range.

See Also

Clamp


FillLongword

procedure FillLongword(var X; Count: Integer; Value: Longword);

Description

An optimized analogue of FillChar for 32 bit values.

See Also

FillWord


FillWord

procedure FillWord(var X; Count: Integer; Value: Longword);

Description

An optimized analogue of FillChar for 16 bit values. Note that only the lower word of the Value parameter is used.

See Also

FillLongword


Mirror

function Mirror(Value: Integer; Max: Integer): Integer; overload;

function Mirror(Value: Integer; Min: Integer; Max: Integer): Integer; overload;

Description

First version mirrors integer Value in [0..Max] range. E.g. if Value is 10 and Max is 9, result will be 8.

Second version mirrors integer Value in [Min..Max] range.

This function is used in TWrapMode wmMirror.

See Also

Clamp, TWrapMode, Wrap


MoveLongword

procedure MoveLongword(const Source; var Dest; Count: Integer);

Description

An analogue of Move for 32 bit values.

See Also

MoveWord


MoveWord

procedure MoveWord(const Source; var Dest; Count: Integer);

Description

An analogue of Move for 16 bit values.

See Also

MoveLongword


Shift Arithmetic Right

function SAR_4(Value: Integer): Integer; // Value div 16

function SAR_8(Value: Integer): Integer; // Value div 256

function SAR_9(Value: Integer): Integer; // Value div 512

function SAR_11(Value: Integer): Integer;

function SAR_12(Value: Integer): Integer;

function SAR_13(Value: Integer): Integer;

function SAR_14(Value: Integer): Integer;

function SAR_15(Value: Integer): Integer;

function SAR_16(Value: Integer): Integer;

Description

Auxiliary arithmetic shift right routines (SAR). These can be used for faster division of signed integers. SAR differs from the shr instruction by preserving the sign of the Value. For example, calling SAR_4 equals Value div 16 (2^4) and calling SAR_9 equels Value div 512 (2^9).


Swap

procedure Swap(var A: Integer; var B: Integer);

Description

Exchange two 32-bit values.

See Also

FillWord


SwapConstrain

function SwapConstrain(const Value: Integer; Constrain1: Integer; Constrain2: Integer): Integer;

Description

Returns Value constrained to [Min(Constrain1, Constrain2)..Max(Constrain1, Constrain2] range.

See Also

Clamp, Constrain, Swap


TestClip

function TestClip(var A: Integer; var B: Integer; const Size: Integer): Boolean; overload;

function TestClip(var A: Integer; var B: Integer; const Start: Integer; const Stop: Integer): Boolean; overload;

Description

First version: Exchange A <-> B only if B < A, then restrict both to [0..Size-1] range. Returns true if resulting range has common points with [0..Size-1] range.

Second version: Exchange A <-> B only if B < A, then restrict both to [Start..Stop-1] range. Returns true if resulting range has common points with [Start..Stop-1] range.

See Also

Clamp, Constrain


TestSwap

procedure TestSwap(var A: Integer; var B: Integer);

Description

Exchange A <-> B only if B < A.

See Also

TestClip


Wrap

function Wrap(Value: Integer; Max: Integer): Integer; overload;

function Wrap(Value: Integer; Min: Integer; Max: Integer): Integer; overload;

Description

First version wraps integer Value in [0..Max] range. E.g. if Value is 10 and Max is 9, result will be 0.

Second version wraps integer Value in [Min..Max] range.

This function is used in TWrapMode wmRepeat.

See Also

Clamp, Mirror, TWrapMode


GR32_Math

GR32_Math.pas is a collection of math related functions used in Graphics32.

Contents

Routines
Fixed Ceil
Fixed Division
Fixed Floor
Fixed Multiply
Fixed Round
Fixed Square
Fixed Square Root
SinCos


Fixed Ceil

FixedCeil

function FixedCeil(A: TFixed): Integer;

An implementation of the Ceil function for TFixed type.

See Also

Fixed Floor, Fixed Point Math, Fixed Round, TFixed


Fixed Division

FixedDiv

function FixedDiv(A, B, TFixed): TFixed;

This is the same as using MulDiv(A, $10000, B).

See Also

Fixed Multiply, Fixed Point Math, TFixed


Fixed Floor

FixedFloor

function FixedFloor(A: TFixed): Integer;

An analogue to Floor function.

See Also

Fixed Ceil, Fixed Point Math, Fixed Round, TFixed


Fixed Multiply

FixedMul

function FixedMul(A, B, TFixed): TFixed;

This is the same as using MulDiv(A, B, $10000).

See Also

Fixed Division, Fixed Point Math, TFixed


Fixed Round

FixedRound

function FixedRound(A, B, TFixed): TFixed;

Provides correct rounding of fixed-point values.

See Also

Fixed Point Math, TFixed


Fixed Square

FixedSqr

function FixedSqr(Value: TFixed): TFixed;

This is the same as using FixedMul(Value, Value).

See Also

Fixed Point Math, Fixed Square Root, TFixed


Fixed Square Root

FixedSqrtLP

function FixedSqrtLP(Value: TFixed): TFixed;

Low precision (8 bit) fixed math squareroot.

FixedSqrtHP

function FixedSqrtHP(Value: TFixed): TFixed;

High precision (16 bit) fixed math square root. This routine is slower that the low precision version.

See Also

Fixed Point Math, Fixed Square, TFixed


SinCos

SinCos

proc edure SinCos(const Theta: Single; var Sin: Single; var Cos: Single); overload;

proc edure SinCos(const Theta: Single; const Radius: Single; var Sin: Single; var Cos: Single); overload;

Single precision versions of SinCos.


GR32_OrdinalMaps

GR32_OrdinalMaps.pas is a collection of ordinal type map classes.

Contents

Types | Classes
TConversionType | TBooleanMap
 | TByteMap
 | TIntegerMap
 | TWordMap


TConversionType

type TConversionType = (
ctRed,
ctGreen,
ctBlue,
ctAlpha,
ctUniformRGB,
ctWeightedRGB);

Description

Specifies how data is converted from 32-bit ARGB bitmap to 8-bit bytemap and back.

See Also

TByteMap.ReadFrom, TByteMap.WriteTo


TBooleanMap

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TCustomMap

Description

The TBooleanMap class implements a two dimensional matrix of booleans. It may be useful for storing masks or information about areas to process, and in general data that requires or can be represented as boolean types. The class implements efficient storage of booleans: a boolean value only takes up one bit of memory, and is stored in sets of eight bits (one byte).

Reference

Fields | Methods | Properties | Events
In TBooleanMap:
 |  | Bits |
 |  | Value |
In TCustomMap:
 | Delete | Height | OnResize
 | Empty | Width |
 | Resized |  |
 | SetSize |  |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Create |  |
 | Destroy |  |
 | EndUpdate |  |

See Also

TByteMap, TIntegerMap, TWordMap


Bits

TBooleanMap.Bits

property Bits: PByteArray;

Description

Returns the pointer to the internal array of byte packed bits. Data is stored in row-major order, top-left "pixel" comes first. Note that since the boolean map stores its values packed in bytes (8 bits or booleans per byte), the last element of the array may contain invalid values. It is recommened only to process width * height - 1 elements, and use the value property to change the last packed byte element of the array.

See Also

Arrays, Value


Value

TBooleanMap.Value

property Value[X, Y: Integer]: Boolean; default;

Description

Provides coordinate-based access to stored booleans. This function does not perform any range checking of its arguments. Be sure, that the boolean map is not empty and that both X and Y are in a valid range.


TByteMap

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TCustomMap

Description

The TByteMap class may be used to simulate palette-based operations or to access separate color layers in TBitmap32.

TByteMap is an ancestor of TCustomMap and is assignment compatible with TBitmap32 objects in both directions.

Reference

Fields | Methods | Properties | Events
In TByteMap:
 | Assign | Bits |
 | Clear | ValPtr |
 | Destroy | Value |
 | Empty |  |
 | ReadFrom |  |
 | SetSize |  |
 | WriteTo |  |
In TCustomMap:
 | Delete | Height | OnResize
 | Resized | Width |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Create |  |
 | EndUpdate |  |

See Also

Examples, TBitmap32, TBooleanMap, TCustomMap, TIntegerMap, TWordMap


Assign

TByteMap.Assign

procedure Assign(Source: TPersistent); override;

Description

Copies data from another object, specified by the Source parameter.

This method supports following classes:

  • nil – assigns an empty data array;
  • TByteMap – copies data bytes from another byte map;
  • TBitmap32 – transforms bitmap data using the ReadFrom method with ctWeightedRGB conversion type.

TByteMap also overrides the protected AssignTo method, making it possible to assign bitmaps from byte maps, so that both following lines are correct:

ByteMap.Assign(Bitmap32); // an analog to BM := Intensity(B32);

Bitmap32.Assign(ByteMap); // an analog to B32 := Gray32(BM);

See Also

ReadFrom, TByteMap


Clear

TByteMap.Clear

procedure Clear(FillValue: Byte);

Description

Fills the entire byte map with the specified value.


Destroy

TByteMap.Destroy

destructor Destroy; override;

Description

Destroys the bytemap object and frees all the associated memory.

Do not call Destroy directly, use the Free method instead.


Empty

TByteMap.Empty

function Empty: Boolean; override;

Description

Returns True if the byte map contains no data, that is Width or Height is equal to 0.

See Also

TCustomMap.Height, TCustomMap.Width


ReadFrom

TByteMap.ReadFrom

procedure ReadFrom(Source: TBitmap32; Conversion: TConversionType);

Description

ReadFrom allows reading and converting data from TBitmap32 objects into the byte map.

First, the byte map is resized to fit the Source bitmap dimensions, then the 32-bit RGBA color is transformed to 8-bits depending on the conversion type:

Conversion | Action
ctRed | Copies red channel
ctGreen | Copies green channel
ctBlue | Copies blue channel
ctAlpha | Copies alpha channel
ctUniformRGB | Copies averaged value: (R + G + B) / 3
ctWeightedRGB | Copies intensity: R * 0.21 + G * 0.71 + B * 0.08

See Also

TBitmap32, TConversionType


SetSize

TByteMap.SetSize

function SetSize(NewWidth, NewHeight: Integer): Boolean; override;

procedure SetSize(Source: TPersistent); // implemented in TCustomMap

Description

Call SetSize to set new dimensions of the bytemap. If one of the arguments is zero, the bytemap is considered empty and its Bits property is set to nil.

Calling SetSize works faster than changing both Width and Height properties.

If you use another bitmap, byte map or control as an argument, the byte map will be sized to corresponding dimensions.

See Also

Bits, TCustomMap.Height, TCustomMap, TCustomMap.Width


WriteTo

TByteMap.WriteTo

procedure WriteTo(Dest: TBitmap32; Conversion: TConversionType); overload;
procedure WriteTo(Dest: TBitmap32; const Palette: TPalette32); overload;

Description

WriteTo fills the Dest bitmap using the values stored in the byte map.

If it is necessary, the destination bitmap is resized to fit the byte map dimensions.

The following table shows how 8-bit data is transformed into 32-bit RGBA color depending on Conversion parameter.

Conversion | Action
ctRed | Copies bytes into red channel
ctGreen | Copies bytes into green channel
ctBlue | Copies bytes into blue channel
ctAlpha | Copies bytes into alpha channel
ctUniformRGB | Copies the same byte value into red, green and blue channels.
ctWeightedRGB

WriteTo method does not distinguish between ctUniformRGB and ctWeightedRGB conversion types.

Note, that this method alters only the specified color channels, other channels remain intact.

The second overloaded version with Palette parameter uses TPalette32 array to map byte values into RGBA colors.

See Also

TBitmap32, TConversionType, Color Types


Bits

TByteMap.Bits

property Bits: PWordArray;

Description

Returns the pointer to the internal array of words. Data is stored in row-major order, top-left "pixel" comes first.

See Also

Arrays, ValPtr, Value


ValPtr

TByteMap.ValPtr

property ValPtr[X, Y: Integer]: PByte;

Description

Returns a pointer to the specific byte in the array.


Value

TByteMap.Value

property Value[X, Y: Integer]: Byte; default;

Description

Provides coordinate-based access to stored bytes. This function does not perform any range checking of its arguments. Be sure, that the byte map is not empty and that both X and Y are in a valid range.


TIntegerMap

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TCustomMap

Description

The TIntegerMap class implements a two dimensional matrix of integers. It may be useful for storing height map data, and in general data that requires or can be represented as 32 bit signed integers.

Reference

Fields | Methods | Properties | Events
In TIntegerMap:
 |  | Bits |
 |  | ValPtr |
 |  | Value |
In TCustomMap:
 | Delete | Height | OnResize
 | Empty | Width |
 | Resized |  |
 | SetSize |  |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Create |  |
 | Destroy |  |
 | EndUpdate |  |

See Also

GR32_OrdinalMaps, TBooleanMap, TWordMap


Bits

TIntegerMap.Bits

property Bits: PIntegerArray;

Description

Returns the pointer to the internal array of integers. Data is stored in row-major order, top-left "pixel" comes first.

See Also

Arrays, ValPtr, Value


ValPtr

TIntegerMap.ValPtr

property ValPtr[X, Y: Integer]: PInteger;

Description

Returns a pointer to the specific integer in the array.


Value

TIntegerMap.Value

property Value[X, Y: Integer]: Integer; default;

Description

Provides coordinate-based access to stored integers. This function does not perform any range checking of its arguments. Be sure, that the map is not empty and that both X and Y are in a valid range.


TWordMap

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TCustomMap

Description

The TWordMap class implements a two dimensional matrix of words. It may be useful for storing 16 bit grayscale data, and in general data that requires or can be represented in 16 bit unsigned integers (words).

Reference

Fields | Methods | Properties | Events
In TWordMap:
 |  | Bits |
 |  | ValPtr |
 |  | Value |
In TCustomMap:
 | Delete | Height | OnResize
 | Empty | Width |
 | Resized |  |
 | SetSize |  |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Create |  |
 | Destroy |  |
 | EndUpdate |  |

See Also

GR32_OrdinalMaps, TBooleanMap, TIntegerMap


Bits

TWordMap.Bits

property Bits: PByteArray;

Description

Returns the pointer to the internal array of bytes. Data is stored in row-major order, top-left "pixel" comes first.

See Also

Arrays, ValPtr, Value


ValPtr

TWordMap.ValPtr

property ValPtr[X, Y: Integer]: PWord;

Description

Returns a pointer to the specific word in the array.


Value

TWordMap.Value

property Value[X, Y: Integer]: Word; default;

Description

Provides coordinate-based access to stored words. This function does not perform any range checking of its arguments. Be sure, that the map is not empty and that both X and Y are in a valid range.


GR32_Polygons

GR32_Polygons.pas provides functions and classes for drawing polygons and polylines.

Contents

Types | Classes | Routines | Constants
TAntialiasMode | TBitmapPolygonFiller | Polygon | DefaultAAMode
TFillLineEvent | TCustomPolygonFiller | Polyline |
TPolyFillMode | TPolygon32 | PolyPolygon |
 |  | PolyPolygonBounds |
 |  | PolyPolyline |
 |  | PtInPolygon |


TAntialiasMode

type TAntialiasMode = (am32times, am16times, am8times, am4times, am2times);

Description

Specifies how polygons are antialiased.

Here is a small illustration that demonstrates the different modes and their output quality:

32x supersampling generally generates the best result. However, it is also the slowest mode.
16x supersampling generates a very smooth result. Generally, there is no noticeable difference in quality between this and the 32x mode.
8x supersampling is a good compromise between speed and quality.
4x supersampling offers an acceptable tradeoff between speed and quality.
2x supersampling offers the worst quality, but still has a higher precision than rendering without any antialiasing.

If you need fast but still antialiased polygons (for example in an editor) we recommend using the 4x or 8x antialias mode.

See Also

Polygon


TFillLineEvent

type TFillLineEvent = procedure(Dst: PColor32; DstX, DstY, Length: Integer; AlphaValues: PColor32) of object;

Description

Use this definition to create custom fill line callbacks.

Dst specifies the first position in the destination buffer that needs to be drawn to. You can use the coordinates DstX and DstY for calculations.

Length determines the length of the line to draw.

AlphaValues is a pointer to the first alpha value of the edge for each pixel on that line. This is used by the PolygonXS and PolyPolygonXS procedures only. For PolygonTS and PolyPolygonTS this parameter is nil, so please do appropriate checks.

Callbacks based on this specification cann be used with the DrawFill and Draw methods of TPolygon32 or with the Polygon and PolyPolygon routines.

See Also

TPolygon32.Draw, TPolygon32.DrawFill, Polygon, PolyPolygon, TPolygon32


TPolyFillMode

type TPolyFillMode = (pfAlternate, pfWinding);

Description

Specifies how polygons are filled.

See Also

Polygon


Polygon

procedure PolygonTS(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; Color: TColor32; Mode: TPolyFillMode = pfAlternate; Transformation: TTransformation = nil); overload;

procedure PolygonTS(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; FillLineCallback: TFillLineEvent; Mode: TPolyFillMode = pfAlternate; Transformation: TTransformation = nil); overload;

procedure PolygonTS(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; Filler: TCustomPolygonFiller; Mode: TPolyFillMode = pfAlternate; Transformation: TTransformation = nil); overload;

procedure PolygonXS(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; Color: TColor32; Mode: TPolyFillMode = pfAlternate; AAMode: TAntialiasMode = DefaultAAMode; Transformation: TTransformation = nil); overload;

procedure PolygonXS(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; FillLineCallback: TFillLineEvent; Mode: TPolyFillMode = pfAlternate; AAMode: TAntialiasMode = DefaultAAMode; Transformation: TTransformation = nil); overload;

procedure PolygonXS(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; Filler: TCustomPolygonFiller; Mode: TPolyFillMode = pfAlternate; AAMode: TAntialiasMode = DefaultAAMode; Transformation: TTransformation = nil); overload;

Description

Fills the shape defined by the Points parameter and (optionally) transformed by the Transformation parameter using one of the following options:

  • simple color
  • custom fillline callback
  • custom filler object

Unlike GDI polygons, this function allows for transparency and optional antialiasing.

PolygonTS draws a non-antialiased polygon with optional transparency. When drawing, fixed-point coordinates of vertices are rounded.

PolygonXS provides full antialiasing and does not perform rounding of vertex coordinates. You can also specify the antialias mode AAMode that should be used.

All functions perform clipping.

See Also

DefaultAAMode, Naming Conventions, TAntialiasMode, Point Types, Color Types, TCustomBitmap32, TCustomPolygonFiller, TFillLineEvent, TPolyFillMode, TTransformation


Polyline

procedure PolyLineTS(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; Color: TColor32; Closed: Boolean=True; Transformation: TTransformation = nil);

procedure PolyLineAS(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; Color: TColor32; Closed: Boolean=True; Transformation: TTransformation = nil);

procedure PolyLineXS(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; Color: TColor32; Closed: Boolean=True; Transformation: TTransformation = nil);

procedure PolyLineXSP(Bitmap: TCustomBitmap32; const Points: TArrayOfFixedPoint; Closed: Boolean=True; Transformation: TTransformation = nil);

Description

Draws a series of lines, connecting points passed in. The points are transformed by Transformation. If Closed is True, the polygon is closed automatically by drawing a line from the last vertex to the first.

PolyLineTS draws a non-antialiased line with optional transparency. When drawing, fixed-point coordinates of vertixes are rounded.

PolyLineAS draws an antialiased line, fixed-point coordinates of vertexes are rounded.

PolyLineXS provides full antialiasing and does not perform rounding of vertexes' coordinates. PolyLineXSP uses the stipple pattern defined in the Bitmap instead of a color.

All functions perform clipping.

See Also

Naming Conventions, Point Types, Color Types, TCustomBitmap32, TTransformation


PolyPolygon

procedure PolyPolygonTS(Bitmap: TCustomBitmap32; const Points: TArrayOfArrayOfFixedPoint; Color: TColor32; Mode: TPolyFillMode = pfAlternate);

procedure PolyPolygonXS(Bitmap: TCustomBitmap32; const Points: TArrayOfArrayOfFixedPoint; Color: TColor32; Mode: TPolyFillMode = pfAlternate; AAMode: TAntialiasMode = DefaultAAMode);

Description

Fills the shape similar to that done by Polygon function. The shape is constructed from several contours, which are specified in Points parameter. The filling is performed according to Mode parameter.

For PolyPolygonXS you can also specify the antialias mode that should be used.

See Also

DefaultAAMode, Naming Conventions, Polygon, PolyPolyline, TAntialiasMode, Point Types, Color Types, TCustomBitmap32, TPolyFillMode


PolyPolygonBounds

function PolyPolygonBounds(const Points: TArrayOfArrayOfFixedPoint): TFixedRect;

Description

Returns the boundaries of the input array.

See Also

Point Types, Rectangle Types


PolyPolyline

procedure PolyPolylineTS(Bitmap: TCustomBitmap32; const Points: TArrayOfArrayOfFixedPoint; Color: TColor32; Closed: Boolean=True; Transformation: TTransformation=nil);

procedure PolyPolylineAS(Bitmap: TCustomBitmap32; const Points: TArrayOfArrayOfFixedPoint; Color: TColor32; Closed: Boolean=True; Transformation: TTransformation=nil);

procedure PolyPolylineXS(Bitmap: TCustomBitmap32; const Points: TArrayOfArrayOfFixedPoint; Color: TColor32; Closed: Boolean=True; Transformation: TTransformation=nil);

procedure PolyPolylineXSP(Bitmap: TCustomBitmap32; const Points: TArrayOfArrayOfFixedPoint; Closed: Boolean=True; Transformation: TTransformation=nil);

Description

PolyPolyline is the same as Polyline, but takes array of polylines as parameter. The Closed parameter influences all polylines in the array.

See Also

Naming Conventions, Polyline, PolyPolygon, Point Types, Color Types, TCustomBitmap32


PtInPolygon

function PtInPolygon(const Pt: TFixedPoint; const Points: TArrayOfFixedPoint): Boolean;

Description

Returns true if Pt is a coordinate within the the polygon region specified by an array of fixed-point coordinates.

See Also

TPolygon32.ContainsPoint, Point Types, Point Types, Point Types


DefaultAAMode

The DefaultAAMode constant of type TAntialiasMode sets the default antialias mode to am8times.

See Also

TAntialiasMode


TBitmapPolygonFiller

Hierarchy

TObject

|

TCustomPolygonFiller

Description

TBitmapPolygonFiller provides an easy way to have a polygon filled with a pattern (TCustomBitmap32).

It fully supports the pattern's DrawMode setting. Custom pixel combiners are also supported.

You can directly use it in the DrawFill and Draw methods of TPolygon32 or in the Polygon and PolyPolygon routines.

Reference

Fields | Methods | Properties
In TBitmapPolygonFiller:
 |  | OffsetX
 |  | OffsetY
 |  | Pattern
In TCustomPolygonFiller:
 | GetFillLine |

See Also

TPolygon32.Draw, TPolygon32.DrawFill, TCustomBitmap32.DrawMode, TCustomBitmap32.OnPixelCombine, Polygon, PolyPolygon, TCustomBitmap32, TCustomPolygonFiller, TPolygon32


OffsetX

TBitmapPolygonFiller.OffsetX

property OffsetX: Integer;

Description

Determines how much in pixels the tiling should be shifted in horizontal direction.

This is especially usefull if your polygon is moved and you want to move the pattern tiling relatively to it.


OffsetY

TBitmapPolygonFiller.OffsetY

property OffsetY: Integer;

Description

Determines how much in pixels the tiling should be shifted in vertical direction.

This is especially usefull if your polygon is moved and you want to move the pattern tiling relatively to it.


Pattern

TBitmapPolygonFiller.Pattern

property Pattern: TCustomBitmap32;

Description

This property determines the pattern that is used to fill a polygon. The pattern will be tiled across the polygons.

Please note that the draw transformation won't have any effect on the polygon. For that purpose please preprocess your pattern accordingly.

See Also

TCustomBitmap32


TCustomPolygonFiller

Hierarchy

TObject

Description

In addition to the standard color fillings for polygons, Graphics32 provides the ability to create new custom polygon fillers based on the TCustomPolygonFiller class or a TFillLineEvent-based callback.

If you want to create your own polygon filler, subclass from this class and override the GetFillLine method.

All classes based on TCustomPolygonFiller can be used with the DrawFill and Draw methods of TPolygon32 or with the Polygon and PolyPolygon routines.

Note: Don't use this class directly as it is partly abstract.

Reference

Fields | Methods | Properties
In TCustomPolygonFiller:
 | GetFillLine |

See Also

TPolygon32.Draw, TPolygon32.DrawFill, Polygon, PolyPolygon, TBitmapPolygonFiller, TFillLineEvent, TPolygon32


GetFillLine

TCustomPolygonFiller.GetFillLine

function GetFillLine: TFillLineEvent; abstract;

Description

Descendants should override this abstract method. If overriden it should return a TFillLineEvent callback that is used to fill lines in a polygon.

See Also

TFillLineEvent


TPolygon32

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

Description

In addition to common polygon drawing functions, Graphics32 provides an auxiliary class TPolygon32, which may be used for storing and drawing polygons and polylines, allowes drawing of lines and polylines more than 1 pixel wide and provides some morphological modifications of polygons.

TPolygon32 is capable of storing more than a single polygon, it can represent a shape, outlines by several polygons, referred here as contours and specified in Points property. This allows rendering of comples shapes (with holes, etc.). In future versions we plan to implement direct TTF or Type1 font rendering.

Contour is considered as a closed polygon if the Closed property is True, otherwise it is treated as polyline. Each contour is, in turn, a dynamic array of TFixedPoint.

Polygons may be constructed by modifying other polygons using the Grow method or by adding sequentially new points with Add or starting new contours with NewLine.

Reference

Fields | Methods | Properties | Events
In TPolygon32:
 | Add | Antialiased |
 | AddPoints | AntialiasMode |
 | Assign | Closed |
 | Clear | FillMode |
 | ContainsPoint | Normals |
 | Create | Points |
 | Destroy |  |
 | Draw |  |
 | DrawEdge |  |
 | DrawFill |  |
 | GetBoundingRect |  |
 | Grow |  |
 | NewLine |  |
 | Offset |  |
 | Outline |  |
 | Transform |  |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

Examples, Point Types


Add

TPolygon32.Add

procedure Add(const P: TFixedPoint);

Description

Adds a new vertex to the current contour in the polygon. In order to start a new contour, use the NewLine method.

See Also

NewLine, Point Types


AddPoints

TPolygon32.AddPoints

procedure AddPoints(const First: TFixedPoint; Count: Integer);

Description

Copies Count number of points beginning at point First to the current outline.

See Also

Point Types


Assign

TPolygon32.Assign

procedure Assign(Source: TPersistent); virtual;

Description

If Source is also of type TPolygon32, Assign copies all properties, points and normals over to the current instance. The old values are replaced in this process.

See Also

TPolygon32


Clear

TPolygon32.Clear

procedure Clear;

Description

Clears the information on all contours, associated with the polygon.


ContainsPoint

TPolygon32.ContainsPoint

function ContainsPoint(const P: TFixedPoint): Boolean;

Description

This method returns true if a point P is contained within any of the contours in the current TPolygon32 instance and false otherwise.

See Also

Point Types, PtInPolygon, Point Types


Create

TPolygon32.Create

constructor Create; override;

Description

Creates and initializes an instance of TPolygon32.

After calling the inherited constructor, Create initializes the following properties:

  • Closed to True;
  • Antialiazed to False;
  • FillMode to pfAlternate;

See Also

Antialiased, Closed, FillMode, TPolygon32


Destroy

TPolygon32.Destroy

destructor Destroy; override;

Description

Destroys the polygon object and frees all associated memory.

Do not call Destroy directly, use Free method instead.


Draw

TPolygon32.Draw

procedure Draw(Bitmap: TCustomBitmap32; OutlineColor, FillColor: TColor32; Transformation: TTransformation = nil); overload;

procedure Draw(Bitmap: TCustomBitmap32; OutlineColor: TColor32; FillLineCallback: TFillLineEvent; Transformation: TTransformation = nil); overload;

procedure Draw(Bitmap: TCustomBitmap32; OutlineColor: TColor32; Filler: TCustomPolygonFiller; Transformation: TTransformation = nil); overload;

Description

Fills the polygon and draws the outline transformed by Transformation. This method is a simple combination of DrawFill and DrawEdge methods.

See Also

DrawEdge, DrawFill, Color Types, TCustomBitmap32, TCustomPolygonFiller, TFillLineEvent, TTransformation


DrawEdge

TPolygon32.DrawEdge

procedure DrawEdge(Bitmap: TCustomBitmap32; Color: TColor32 ; Transformation: TTransformation = nil);

Description

Frames the edge of the polygon with specified color and uses the Transformation while drawing.

The quality of the line is determined by Antialiased property.

When Closed property is True, each polygon is automatically closed.

See Also

Antialiased, Closed, Draw, DrawFill, Color Types, TCustomBitmap32, TTransformation


DrawFill

TPolygon32.DrawFill

procedure DrawFill(Bitmap: TCustomBitmap32; Color: TColor32; Transformation: TTransformation = nil); overload;

procedure DrawFill(Bitmap: TCustomBitmap32; FillLineCallback: TFillLineEvent; Transformation: TTransformation = nil); overload;

procedure DrawFill(Bitmap: TCustomBitmap32; Filler: TCustomPolygonFiller; Transformation: TTransformation = nil); overload;

Description

Fills the polygon shape using one of the following options using the current FillMode:

  • simple color
  • custom fillline callback
  • custom filler object

Optionally a Transformation is applied while drawing.

The Closed property is ignored and all contours are automatically considered closed.

The edge quality of the filling is determined by the Antialiased property.

See Also

Antialiased, Closed, Draw, DrawEdge, FillMode, Color Types, TCustomBitmap32, TCustomPolygonFiller, TFillLineEvent, TTransformation


GetBoundingRect

TPolygon32.GetBoundingRect

function GetBoundingRect: TFixedRect;

Description

Returns the common bounding rectangle for all outlines in the current polygon.

See Also

Rectangle Types


Grow

TPolygon32.Grow

function Grow(const Delta: TFixed; EdgeSharpness: Single = 0): TPolygon32;

Description

Creates a new instance of TPolygon32 object and changes its shape similar to dilation (or erosion when Delta is negative) morphological filters.

The direction of grouth is determined by the order of the points in the contour. Positive direction is to the left of each line (see image below).

Using Grow method with Delta = 0 will simply create a new instance of the polygon with the same data as in original polygon.

The EdgeSharpness parameter controls generation of new vertices. Its value range is [0…0.99].

See Also

TFixed, TPolygon32


NewLine

TPolygon32.NewLine

procedure NewLine;

Description

Starts a new contour. New points, introduced with Add function, will be inserted into the new contour.

See Also

Add


Offset

TPolygon32.Offset

procedure Offset(const Dx, Dy: TFixed);

Description

Shifts all the points in all contours Dx pixels right and Dy pixels down. Values of Dx and Dy can be negative.

See Also

TFixed


Outline

TPolygon32.Outline

function Outline: TPolygon32;

Description

This functions takes each contour (polyline) and constructs a new TPolygon32 object by outlining each contour.

The operation is similar to using morphological edge detection filter for bitmaps, but it operates over polygon vertices.

When outlining a closed polygon, this function actually returns two contours for each initial closed contour. In case of polylines (Closed property is False), it returns a single contour (see image below).

Note, this technique produces good results only for antialiased polygons.

This function is essential for thick line drawing, all you have to do, is to take an original polygon, build its outline and grow it to get the desired thickness:

var
P, Outline: TPolygon32;
begin
Outline := P.Outline; // create an outline
Outline.Grow(Fixed(1), 1); // make it 2-pixel wide outline (it grows in both directions)
Outline.DrawFill(DstBitmap, clBlack32);
end;

See Also

Closed, TPolygon32


Transform

TPolygon32.Transform

procedure Transform(Transformation: TTransformation);

Description

Transforms all points in the current instance using the supplied Transformation instance. This is different from the transformation while drawin because it is a permanent operation.

See Also

TTransformation


Antialiased

TPolygon32.Antialiased

property Antialiased: Boolean;

Description

Determines the quality of the shape when it is drawn with Draw, DrawFill or DrawEdge methods.

When Antialiased = False, the object uses PolyPolylineTS and PolyPolygonTS functions, otherwise, it uses PolyPolylineXS and PolyPolygonXS functions.

See Also

Draw, DrawEdge, DrawFill, PolyPolyline


AntialiasMode

TPolygon32.AntialiasMode

property AntialiasMode: TAntialiasMode;

Description

Determines how the shape is antialiased. See TAntialiasMode for details.

See Also

TAntialiasMode


Closed

TPolygon32.Closed

property Closed: Boolean;

Description

Specifies whether each contour defined by Points is a closed shape, or if it has to be considered as polyline.

This property is ignored by Draw and DrawFill methods, but it is important when using Outline method.

See Also

Draw, DrawFill, Outline, Points


FillMode

TPolygon32.FillMode

property FillMode: TPolyFIllMode;

Description

Determines the shape's fill mode.

See Also

TPolyFillMode


Normals

TPolygon32.Normals

property Normals: TArrayOfArrayOfFixedPoint;

Description

This array stores unit vectors showing the direction normal to each line in each contour. Normals are used in Grow.

See Also

Grow, Points, Point Types


Points

TPolygon32.Points

property Points: TArrayOfArrayOfFixedPoint;

Description

This property defines an array of contours. Each contour is, in turn, an array of vertexes.

See Also

Normals, Point Types


GR32_RangeBars

GR32_RangeBars.pas provides controls similar to standard TScrollBar and TControlScrollBar. This unit is included into Graphics32 to provide customized scroll bars for TCustomImgView32 and TImgView32 to scroll their contents.

Contents

Types | Classes
TRBBackgnd | TArrowBar
TRBStyle | TCustomGaugeBar
 | TCustomRangeBar
 | TGaugeBar
 | TRangeBar

See Also

TCustomImgView32, TImgView32


TRBBackgnd

type TRBBackgnd = (bgPattern, bgSolid);

Description

Specifies a type of background filling of the arrow bar control and its descendants. See TArrowBar.Backgnd for more information.

See Also

TArrowBar.Backgnd


TRBStyle

type TRBStyle = (bgDefault, bgMac);

Description

Specifies the arrow bar style. See TArrowBar.Style for more information.

See Also

TArrowBar.Style


TArrowBar

Hierarchy

TCustomControl

Description

A common ancestor for range bars and gauge bars. Both its descendants are similar to standard windows scroll bars. TArrowBar declares common properties which define visual appearance of scroll bars.

Reference

Fields | Methods | Properties | Events
In TArrowBar:
 | Create | Backgnd | OnChange
 | Destroy | BorderStyle | OnUserChange
 | Paint | ButtonSize |
 |  | HandleColor |
 |  | Kind |
 |  | ShowArrows |
 |  | ShowHandleGrip |
 |  | Style |

See Also

TCustomGaugeBar, TCustomRangeBar


Create

TArrowBar.Create

constructor Create(AOwner: TComponent); override;

Description

Creates and initializes an instance of TArrowBar.

After calling the inherited constructor, Create initializes the following properties:

  • Backgnd to bgPattern;
  • ButtonSize to 0;
  • Color to clBtnShadow;
  • Style to rbsDefault;
  • HandleColor to clBtnShadow;
  • Kind to sbHorizontal;
  • ShowArrows to True;
  • ShowHandleGrip to True;

See Also

Backgnd, ButtonSize, HandleColor, Kind, ShowArrows, ShowHandleGrip, Style, TArrowBar


Destroy

TArrowBar.Destroy

destructor Destroy; override;

Description

Destroys the arrowbar object and frees all associated memory.

Do not call Destroy directly, use Free method instead.


Paint

TArrowBar.Paint

procedure Paint; override;

Description

Paint is overriden from TCustomControl. It draws the bar and scroll buttons.


Backgnd

TArrowBar.Backgnd

property Backgnd: TRBBackgnd;

type TRBBackgnd = (bgPattern, bgSolid);

Description

Determines appearance of the background:

Note, that this property is available only when Style=rbsMac.

See Also

Style, TRBBackgnd


BorderStyle

TArrowBar.BorderStyle

property BorderStyle: TBorderStyle;

type TBorderStyle = (bsNone, bsSingle); // declared in Forms.pas

Description

When BorderStyle is bsSingle, control is painted with a recessed border.


ButtonSize

TArrowBar.ButtonSize

property ButtonSize: Integer;

Description

Specifies the size of the scroll button in pixels.

When ButtonSize is set to 0 (default), this size is calculated and updated automatically to keep the button square.

If you want to hide buttons set ShowArrows property to False.

See Also

ShowArrows


HandleColor

TArrowBar.HandleColor

property HandleColor: TColor;

Description

Specifies a color of the handle:

Although TArrowBar itself does not have any handles, this property is used in descendants TCustomRangeBar and TCustomGaugeBar.

Note, that this property is available only when Style=rbsMac.

See Also

Style, TArrowBar, TCustomGaugeBar, TCustomRangeBar


Kind

TArrowBar.Kind

property Kind: TScrollBarKind;

type TScrollBarKind = (sbHorizontal, sbVertical); // defined in Forms.pas

Description

Indicates orientation of the control.


ShowArrows

TArrowBar.ShowArrows

property ShowArrows: Boolean;

Description

Determines visibility of scrolling buttons.


ShowHandleGrip

TArrowBar.ShowHandleGrip

property ShowHandleGrip: Boolean;

Description

Determines visibility of a handle grip:

Although TArrowBar itself does not have any handles, this property is used in descendants TCustomRangeBar and TCustomGaugeBar.

Note, that this property is available only when Style=rbsMac.

See Also

Style, TArrowBar, TCustomGaugeBar, TCustomRangeBar


Style

TArrowBar.Style

property Style: TRBStyle;

type TRBStyle = (rbsDefault, rbsMac);

Description

Determines appearance of the control. Note that some properties are accessible only when Style is set to rbsMac.

The default value is rbsDefault;


OnChange

TArrowBar.OnChange

property OnChange: TNotifyEvent;

Description

OnChange is called each time control changes.

This event is never called by TArrowBar itself, but it is shared by descendants TCustomRangeBar and TCustomGaugeBar.

See Also

OnUserChange, TArrowBar, TCustomGaugeBar, TCustomRangeBar


OnUserChange

TArrowBar.OnUserChange

property OnUserChange: TNotifyEvent;

Description

OnUserChange is called when control is changed by user, as reaction to mouse events. It is not called then the control is changed due to some internal program activity. This event is called after OnChange.

This event is never called by TArrowBar itself, but it is shared by descendants TCustomRangeBar and TCustomGaugeBar.

See Also

OnChange, TArrowBar, TCustomGaugeBar, TCustomRangeBar


TCustomGaugeBar

Hierarchy

TCustomControl

|

TArrowBar

Description

A base class for TGaugeBar objects.

Behavior and appearance of TCustomGaugeBar is very similar to standard TScrollBar, defined in StdCtrls.pas.

Reference

Methods | Properties | Events
In TCustomGaugeBar:
Create | HandleSize |
Paint | LargeChange |
 | Max |
 | Min |
 | Position |
 | SmallChange |
In TArrowBar:
Destroy | Backgnd | OnChange
 | BorderStyle | OnUserChange
 | ButtonSize |
 | HandleColor |
 | Kind |
 | ShowArrows |
 | ShowHandleGrip |
 | Style |

See Also

TGaugeBar


Create

TCustomGaugeBar.Create

constructor Create(AOwner: TComponent); override;

Description

Creates and initializes an instance of TCustomGaugeBar.

After calling the inherited constructor, Create initializes the following properties:

  • HandleSize to 0;
  • LargeChange to 1;
  • Max to 100;
  • Min to 0;
  • Position to 0;

See Also

HandleSize, LargeChange, Max, Min, Position, TCustomGaugeBar


Paint

TCustomGaugeBar.Paint

procedure Paint; override;

Description

Paint is overriden from TArrowBar.Paint. In addition to bar and scrolling buttons, it paints the handle.

See Also

TArrowBar.Paint


HandleSize

TCustomGaugeBar.HandleSize

property HandleSize: Integer;

Description

Specifies the size of the handle:

If HandleSize is 0 (default), the size is calculated and updated automatically to keep the handle square.

See Also

TArrowBar.ButtonSize


LargeChange

TCustomGaugeBar.LargeChange

property LargeChange: Integer;

Description

Determines how much Position changes when the user clicks the scroll bar on either side of the handle.

See Also

Position, SmallChange


Max

TCustomGaugeBar.Max

property Max: Integer;

Description

The Max and Min properties define the available range for Position.

See Also

Min, Position


Min

TCustomGaugeBar.Min

property Min: Integer;

Description

The Max and Min properties define the available range for Position.

See Also

Max, Position


Position

TCustomGaugeBar.Position

property Position: Integer;

Description

Specifies the current position of the scrollbar.

Read Position to determine the current position of the thumb tab.

Set Position to programmatically move the handle. The available range of positions is determined by the difference between the Max property and the Min property.

When Position is changed programmatically, gauge bar will generate OnChange event, when it is changed by user (by clicking scrolling buttons, dragging the handle or clicking on the background area), the control will additionally generate OnUserChange event.

See Also

Max, Min, TArrowBar.OnChange, TArrowBar.OnUserChange


SmallChange

TCustomGaugeBar.SmallChange

property SmallChange: Integer;

Description

Determines how much Position changes when the user clicks the scrolling buttons.

See Also

LargeChange, Position


TCustomRangeBar

Hierarchy

TCustomControl

|

TArrowBar

Description

A base class for TRangeBar objects.

Behavior and appearance of TCustomRangeBar is similar to standard TControlScrollBar, defined in Forms.pas, however it does not use the common control library.

Although range bar may operate as a stand-alone control, most of the time you will use it in conjunction with another control, which has a scrollable region:

Range bars are less limited compared to TControlScrollBar. For example, the size of the range bar can be different from the size of the scrollable control and it may be positioned anywhere in the form. Another difference is that range bars do not hide themselves when scrolling range is less than or equal to the size of the scrollable area, they just become disabled.

In addition, range bars have nothing to do with scrollable control's client arrea. They neigher shift client origin, nor determine their range automatically.

Reference

Methods | Properties | Events
In TCustomRangeBar:
Create | Centered |
Paint | Increment |
 | Position |
 | Range |
 | Window |
In TArrowBar:
Destroy | Backgnd | OnChange
 | BorderStyle | OnUserChange
 | ButtonSize |
 | HandleColor |
 | Kind |
 | ShowArrows |
 | ShowHandleGrip |
 | Style |

See Also

TRangeBar


Create

TCustomRangeBar.Create

constructor Create(AOwner: TComponent); override;

Description

Creates and initializes an instance of TCustomRangeBar.

After calling the inherited constructor, Create initializes the following properties:

  • Centered to False;
  • Increment to 8;
  • Position to 0;
  • Range to 0;

See Also

Centered, Increment, Position, Range, TCustomRangeBar


Paint

TCustomRangeBar.Paint

procedure Paint; override;

Description

Paint is overriden from TArrowBar.Paint. In addition to the bar itself and scrolling buttons, it paints the handle.

See Also

TArrowBar.Paint


Centered

TCustomRangeBar.Centered

property Centered: Boolean;

Description

Determines how the handle is repositioned when Range changes.

If Centered is False (default), the control behaves similar to standard TControlScrollBar. That is it tries to preserve the Position property.

If Centered is True, the control changes Position, trying to keep the centre at the same location.

This property also influences how the handle is adjusted when range bar changes its Window size.

See Also

Position, Range, Window


Increment

TCustomRangeBar.Increment

property Increment: Single;

Description

Determines the change in Position when user clicks scrolling arrows.

Default value is 8.

See Also

Position


Position

TCustomRangeBar.Position

property Position: Single;

Description

Determines the current position of the handle.

Note, that Position is a single precision floating-point value. Which allows for more predictable behavior then Centered property is set to True, since the handle won't drift due to rounding errors.

See Also

Centered, Range, Window


Range

TCustomRangeBar.Range

property Range: Single;

Description

Determines the scrollable range.

When range is less than the value stored in Window property(or the size of the control, in case Window = 0), the control draws itself disabled.

See Also

Position, Window


Window

TCustomRangeBar.Window

property Window: Single;

Description

The size of the associated visible area:

In case the value of the property is set to zero, range bar assumes that it is equal to its own size, as shown in the picture above.

Using this property is required when the size of the scrollable window is different from the size of the range bar.

See Also

Position, Range


TGaugeBar

Hierarchy

TCustomControl

|

TArrowBar

|

TCustomGaugeBar

Description

TGaugeBar is a control similar to standard TScrollBar.

TGaugeBar implements the generic behavior introduced in TCustomGaugeBar. It publishes some inherited properties from TCustomGaugeBar, but does not introduce any new behavior.

Reference

Methods | Properties | Events
In TCustomGaugeBar:
Create | HandleSize |
Paint | LargeChange |
 | Max |
 | Min |
 | Position |
 | SmallChange |
In TArrowBar:
Destroy | Backgnd | OnChange
 | BorderStyle | OnUserChange
 | ButtonSize |
 | HandleColor |
 | Kind |
 | ShowArrows |
 | ShowHandleGrip |
 | Style |

See Also

TCustomGaugeBar


TRangeBar

Hierarchy

TCustomControl

|

TArrowBar

|

TCustomRangeBar

Description

TRangeBar is a control similar to standard TControlScrollBar. Normally it is associated with some other control that has a scrollable region.

TRangeBar implements the generic behavior introduced in TCustomRangeBar. It publishes some inherited properties from TCustomRangeBar, but does not introduce any new behavior.

Reference

Fields | Methods | Properties | Events
In TCustomRangeBar:
 | Create | Centered |
 | Paint | Increment |
 |  | Position |
 |  | Range |
 |  | Window |
In TArrowBar:
 | Destroy | Backgnd | OnChange
 |  | BorderStyle | OnUserChange
 |  | ButtonSize |
 |  | HandleColor |
 |  | Kind |
 |  | ShowArrows |
 |  | ShowHandleGrip |
 |  | Style |

See Also

TCustomGaugeBar, TCustomRangeBar


GR32_Rasterizers

GR32_Rasterizers.pas provides classes used when rasterizing an image. Rasterization is the process of acquiring a number of samples for the pixels of a destination image.

Rasterizers determine the order in which pixels are updated in the destination bitmap when sampling from an input scene (which can be a reconstructed bitmap, a synthetic sample generator or an image acquisition device).

Contents

Types | Classes
TCombineInfo | TContourRasterizer
 | TProgressiveRasterizer
 | TRasterizer
 | TRegularRasterizer
 | TSwizzlingRasterizer
 | TTesseralRasterizer


TCombineInfo

PCombineInfo = ^TCombineInfo;

TCombineInfo = record
 SrcAlpha: Integer;
DrawMode: TDrawMode;
CombineMode: TCombineMode;
CombineCallBack: TPixelCombineEvent;
TransparentColor: TColor32;
end;

Description

TCombineInfo contains blending and combine related properties, similar to what is contained in TBitmap32. This structure is used in routines which does not have a single source bitmap, which would normally provide this information (for example a special overloaded version of Rasterize).

See Also

Color Types, TRasterizer.Rasterize, TBitmap32, TCombineMode, TDrawMode, TPixelCombineEvent


TContourRasterizer

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

Description

This rasterizer determines its rasterization path from the intensity difference between samples. It always chooses the path with lowest intensity difference. Due to a higher propability of near execution code and memory loads, this may optimize the CPU cache usage; hence increase in overall performance. To see how this rasterizer works, check the nested sampling example and choose this rasterizer.

Reference

Methods | Properties | Events
In TThreadPersistent:
Lock | LockCount |
Unlock |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
Create |  |
Destroy |  |
EndUpdate |  |

See Also

Examples


TProgressiveRasterizer

Hierarchy

TCustomRasterizer

|

TRasterizer

Description

This rasterizer class provides resolution subdivided rasterization. This is useful for visualizing while rasterizing. The steps property determines the number of intermediate steps in the rasterization. To see how this work, take a look at the nested sampling example with the progressive rasterizer enabled.

Reference

Fields | Methods | Properties
In TProgressiveRasterizer:
 |  | Steps
 |  | UpdateRows
In TRasterizer:
 | Rasterize | Sampler

See Also

Examples


Steps

TProgressiveRasterizer.Steps

property Steps: Integer;

Description

This property controls how many progressive steps the progressive rasterization process will use, i.e. the intermediate resolution progressions.


UpdateRows

TProgressiveRasterizer.UpdateRows

property UpdateRows: Boolean;

Description

This property defines how the rasterizer will trigger repaints. If true, each row of the destination bitmap will be repainted as the rasterizer progress to next row. If false, only step progression will trigger a repaint.

See Also

Steps


TRasterizer

Hierarchy

TCustomRasterizer

Description

The base class for TBitmap32-specific rasterizers. A rasterizer is the final step in a sampler setup, the step responsible for calling the associated samplers and writing the results into the provided destination bitmap. A seperated rasterization process allows for different types of on-screen realizations. For example a progressive rasterizer will increase the resolution of the result in progressive steps, which can keep the end user informed about the progression of the overall process. Moreover it provides perceptual information about the rendering, which can be useful for validation purposes.

Reference

Fields | Methods | Properties
In TRasterizer:
 | Rasterize | Sampler

See Also

Sampling and Rasterization, TBitmap32, TProgressiveRasterizer


Rasterize

TRasterizer.Rasterize

procedure Rasterize(Dst: TBitmap32); overload;

procedure Rasterize(Dst: TBitmap32; const DstRect: TRect); overload;

procedure Rasterize(Dst: TBitmap32; const DstRect: TRect; const CombineInfo: TCombineInfo); overload;

procedure Rasterize(Dst: TBitmap32; const DstRect: TRect; Src: TBitmap32); overload;

Description

Calling rasterize will start the rasterization process.

See Also

Rectangle Types, TBitmap32, TCombineInfo


Sampler

TRasterizer.Sampler

property Sampler: TCustomSampler;

Description

Associates a sampler class, which is used in the rasterization process to retrieve color samples.

See Also

Rasterize, TCustomSampler


TRegularRasterizer

Hierarchy

TCustomRasterizer

|

TRasterizer

Description

The regular rasterizer performs a simple iterative rasterization comparable to a straight forward set of scanline loops. It is also the default rasterization class used internally in Graphics32.

Reference

Methods | Properties
In TRegularRasterizer:
 | UpdateRowCount
In TRasterizer:
Rasterize | Sampler


UpdateRowCount

TRegularRasterizer.UpdateRowCount

property UpdateRowCount: Integer;

Description

This property controls how many rows should be repainted as the rasterization is performed.


TSwizzlingRasterizer

Hierarchy

TCustomRasterizer

|

TRasterizer

Description

A rasterization method where sample locations are choosen according to a fractal pattern called swizzling. An advantage with this pattern is that it may benefit from local coherency in the sampling method used, and moreover optimize the CPU cache usage. To see how this work, take a look at the nested sampling example with the swizzling rasterizer enabled.

Reference

Methods | Properties
In TSwizzlingRasterizer:
 | BlockSize
In TRasterizer:
Rasterize | Sampler

See Also

Examples


BlockSize

TSwizzlingRasterizer.BlockSize

property BlockSize: Integer;

Description

This property controls how large blocks should be repainted as the rasterization is performed. The size of the block is 2^BlockSize.


TTesseralRasterizer

Hierarchy

TCustomRasterizer

|

TRasterizer

Description

This recursive rasterization method uses a divide-and-conquer scheme to subdivide blocks vertically and horizontally. To see how this work, take a look at the nested sampling example with the tesseral rasterizer enabled.

Reference

Methods | Properties
In TRasterizer:
Rasterize | Sampler

See Also

Examples


GR32_Resamplers

GR32_Resamplers.pas provides a comprehensive set of classes that are used within image resampling and rasterization. These classes can roughly be categorized as follows:

  • Resamplers — classes that implement different resampling algorithms;
  • Kernels — convolution kernels used by TKernelResampler;
  • Nested samplers — transformers, super samplers and kernel samplers.

For further information, see topic about Sampling and Rasterization.

Contents

Types | Classes | Routines
TKernelMode | TAdaptiveSuperSampler | BlendTransfer
TPixelAccessMode | TAlbrechtKernel | BlockTransfer
 | TBitmap32Resampler | BlockTransferX
 | TBlackmanKernel | Contract
 | TBoxKernel | Dilate
 | TContracter | Erode
 | TConvolver | Expand
 | TCosineKernel | StretchTransfer
 | TCubicKernel |
 | TCustomKernel |
 | TDilater |
 | TDraftResampler |
 | TEroder |
 | TExpander |
 | TGaussianKernel |
 | THammingKernel |
 | THannKernel |
 | THermiteKernel |
 | TKernelResampler |
 | TKernelSampler |
 | TLanczosKernel |
 | TLinearKernel |
 | TLinearResampler |
 | TMitchellKernel |
 | TMorphologicalSampler |
 | TNearestResampler |
 | TNearestTransformer |
 | TNestedSampler |
 | TPatternSampler |
 | TSelectiveConvolver |
 | TSinshKernel |
 | TSplineKernel |
 | TSuperSampler |
 | TTransformer |
 | TWindowedSincKernel |

See Also

Sampling and Rasterization, TKernelResampler


TKernelMode

type TKernelMode = (kmDynamic, kmTableNearest, kmTableLinear);

Description

TKernelMode defines how a kernel will be used in TKernelResampler, when GetSample methods are called.

  • kmDynamic - Uses direct calls to the kernels filter method. Being precise, this mode is also quite expensive. The curve display in the resamplers example shows how the different weight curves are configured.
  • kmTableNearest - Uses precalculated weight tables. Being the fastest, this mode can produce fair results. An option is to increase the tablesize.
  • kmTableLinear - Uses precalculated weight tables, but in contrast to kmTableNearest this mode will perform linear interpolation between precalculated weights. Being somewhat slower than kmTableNearest, but faster than kmDynamic, this mode produces results good results.

See Also

Examples, TKernelResampler.GetSample, TKernelResampler.TableSize, TCustomKernel, TKernelResampler


TPixelAccessMode

type TPixelAccessMode = (pamUnsafe, pamSafe, pamWrap);

Description

TPixelAccessMode determines how TKernelResampler handles pixels outside the bitmap boundary when invoking the GetSample method.

  • pamUnsafe - No boundary checks are performed. This means that we will read from memory outside the bitmap, if coordinates outside the bitmap area are passed.
  • pamSafe - If the coordinate is outside the clipping rectangle of the bitmap, then the bitmap's outer color will be returned.
  • pamWrap - Coordinates will be wrapped using the current WrapMode and will be restricted to the clipping rectangle.
  • pamTransparentEdge - If the coordinate is outside the clipping rectangle of the bitmap, then a transparent result is returned. Moreover edges are resampled as if there were transparent outer edges. This can be used to achieve antialiased edges when transforming bitmaps with opaque edges; The functionality is similar to SetBorderTransparent.

See Also

TKernelResampler.GetSample, SetBorderTransparent, TKernelResampler, TCustomBitmap32.WrapMode


BlendTransfer

procedure BlendTransfer(
Dst: TCustomBitmap32;
DstX: Integer;
DstY: Integer;
DstClip: TRect;
SrcF: TCustomBitmap32;
SrcRectF: TRect;
SrcB: TCustomBitmap32;
SrcRectB: TRect;
BlendCallback: TBlendReg); overload;

procedure BlendTransfer(
Dst: TCustomBitmap32;
DstX: Integer;
DstY: Integer;
DstClip: TRect;
SrcF: TCustomBitmap32;
SrcRectF: TRect;
SrcB: TCustomBitmap32;
SrcRectB: TRect;
BlendCallback: TBlendRegEx;
MasterAlpha: Integer); overload;

Description

BlendTransfer is a three parameter version of BlockTransfer. SrcF is blended with SrcB via the provided BlendCallback callback routine, and the resulting color is written to the destination. There are two versions, one supporting blend callbacks of type TBlendReg, and one supporting the extended TBlendRegEx. For the latter, the parameter MasterAlpha is passed when calling the extended blendcallback. Note that all blend and combine settings in the provided bitmap parameters are ignored.

See Also

BlockTransfer, Rectangle Types, StretchTransfer, TBlendReg, TBlendRegEx, TCustomBitmap32, Examples


BlockTransfer

procedure BlockTransfer(
Dst: TCustomBitmap32;
DstX: Integer;
DstY: Integer;
DstClip: TRect;
Src: TCustomBitmap32;
SrcRect: TRect;
CombineOp: TDrawMode;
CombineCallBack: TPixelCombineEvent = nil);

Description

BlockTransfer is similar to the BitBlt function from Windows GDI. It performs copying of a bitmap fragment specified by SrcRect into location (DstX, DstY) with optional alpha blending or using user-specified combining function. This operation is constrained to the DstClip rectangle specified in the destination bitmap coordinates.

If CombineOp=dmOpaque, the fragment simply replaces destination pixels. In dmBlend mode it is blended to destination using its alpha channel and MasterAlpha property. In dmCusom mode, the function calls CombineCallBack function for pixel combining.

It is not required for DstRect and SrcRect to lie entirely inside the corresponding bitmap, since the function provides necessary clipping.

The result is not specified when transferring data inside the same bitmap (Src=Dst) and if in the same time SrcRect intersects with DstRect. In this case it is recommended to use a temporary bitmap buffer.

Neither Src nor Dst bitmaps may be equal to nil. In this case, function will generate an exception. They may be empty however, in this case no transformation will be performed.

This routine used in TCustomBitmap32.Draw and TCustomBitmap32.DrawTo methods.

See Also

TCustomBitmap32.Draw, TCustomBitmap32.DrawTo, TCustomBitmap32.MasterAlpha, StretchTransfer, TCustomBitmap32, TDrawMode, TPixelCombineEvent, Rectangle Types


BlockTransferX

procedure BlockTransferX(
Dst: TCustomBitmap32;
DstX: TFixed;
DstY: TFixed;
Src: TCustomBitmap32;
SrcRect: TRect;
CombineOp: TDrawMode;
CombineCallBack: TPixelCombineEvent = nil);

Description

BlockTransferX is an extended version of BlockTransfer that allows a destination coordinate (DstX, DstY) in fixed-point coordinates. This means that the source bitmap is not copied directly but rather transposed a fractional distance before it is copied. In order to still retain reasonable performance, linear interpolation is used for the fractional displacement.

See BlockTransfer for a detailed description.

See Also

BlockTransfer, StretchTransfer, TCustomBitmap32, TDrawMode, TPixelCombineEvent, Rectangle Types


Contract

procedure Contract(Src, Dst: TCustomBitmap32; Kernel: TIntegerMap; CenterX, CenterY: Integer);

Description

Contract performs rasterization using the TContracter sampler. The Kernel parameter specifies a weight matrix which is centered at the coordinated (X + CenterX, Y + CenterY) for each pixel coordinate (X, Y).

Output pixels are computed from the formula

where f corresponds to the source bitmap and b corresponds to the kernel (formally described as a structuring element).

See Also

TContracter, TCustomBitmap32, TIntegerMap


Dilate

procedure Dilate(Src, Dst: TCustomBitmap32; Kernel: TIntegerMap; CenterX, CenterY: Integer);

Description

Dilate performs rasterization using the TDilater sampler. The Kernel parameter specifies a weight matrix which is centered at the coordinated (X + CenterX, Y + CenterY) for each pixel coordinate (X, Y).

Output pixels are computed from the formula

where f corresponds to the source bitmap and b corresponds to the kernel (formally described as a structuring element).

See Also

TCustomBitmap32, TDilater, TIntegerMap


Erode

procedure Erode(Src, Dst: TCustomBitmap32; Kernel: TIntegerMap; CenterX, CenterY: Integer);

Description

Erode performs rasterization using the TEroder sampler. The Kernel parameter specifies a weight matrix which is centered at the coordinated (X + CenterX, Y + CenterY) for each pixel coordinate (X, Y).

Output pixels are computed from the formula

where f corresponds to the source bitmap and b corresponds to the kernel (formally described as a structuring element).

See Also

TCustomBitmap32, TEroder, TIntegerMap


Expand

procedure Expand(Src, Dst: TCustomBitmap32; Kernel: TIntegerMap; CenterX, CenterY: Integer);

Description

Expand performs rasterization using the TExpander sampler. The Kernel parameter specifies a weight matrix which is centered at the coordinated (X + CenterX, Y + CenterY) for each pixel coordinate (X, Y).

Output pixels are computed from the formula

where f corresponds to the source bitmap and b corresponds to the kernel (formally described as a structuring element).

See Also

TCustomBitmap32, TExpander, TIntegerMap


StretchTransfer

procedure StretchTransfer(
Dst: TCustomBitmap32;
DstRect: TRect;
DstClip: TRect;
Src: TCustomBitmap32;
SrcRect: TRect;
StretchFilter: TStretchFilter;
CombineOp: TDrawMode;
CombineCallBack: TPixelCombineEvent = nil);

Description

StretchTransfer is similar to StretchBlt or StretchDIBits functions from WindowsGDI. This procedure performs copying and, if necessary, stretching of the bitmap fragment specified by SrcRect into location in Dst specified by DstRect. This operation is constrained to the DstClip rectangle specified in the destination bitmap coordinates.

For more information on the stretch filters take a look here.

Unlike in BlockTransfer function, SrcRect must lie inside the Src bitmap boundaries, otherwise function will generate an exception. The result is not specified when transferring data inside the same bitmap (Src=Dst) and if in the same time SrcRect intersects with DstRect. In this case it is recommended to use a temporary bitmap buffer.

This routine used in TCustomBitmap32.Draw and TCustomBitmap32.DrawTo methods.

See Also

BlockTransfer, TCustomBitmap32.Draw, TCustomBitmap32.DrawTo, TCustomBitmap32, TDrawMode, TPixelCombineEvent, Rectangle Types, TStretchFilter


TAdaptiveSuperSampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

Description

Adaptive supersampling is different from ordinary supersampling in the sense that samples are choosen adaptively. It is a recursive method that collects more samples at areas with rapid transitions.

The advantage with this method that makes it more attractive than ordinary supersampling is that we can perform supersampling only at areas where it is needed. However, the recursion itself may cause overhead, so there is a trade-off between the cost of the associated nested sampling method and the cost of the adaptive recursion.

Reference

Methods | Properties | Events
In TAdaptiveSuperSampler:
Create | Level |
GetSample | Tolerance |
In TNestedSampler:
 | Sampler |
In TCustomSampler:
FinalizeSampling |  |
GetSampleBounds |  |
HasBounds |  |
PrepareSampling |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
Destroy |  |
EndUpdate |  |


Create

TAdaptiveSuperSampler.Create

procedure Create(Sampler: TCustomSampler); override;

Description

Call Create to instantiate an adaptive super sampler at runtime.

Sampler is an instance of TCustomSampler used to retrieve samples by the adaptive super sampler.


GetSample

TAdaptiveSuperSampler.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


Level

TAdaptiveSuperSampler.Level

property Level: Integer;

Description

This property will set the maximum possible recursion depth.


Tolerance

TAdaptiveSuperSampler.Tolerance

property Tolerance: Integer;

Description

Adaptive supersampling uses a tolerance parameter to limit the recursion depth. If the difference between two samples is less than the tolerance, then the recursion will stop. By default the difference between two colors is computed as the sum of the componentwise differences between the R, G and B components. It is possible to change this evaluation by overriding the protected CompareColors method.


TAlbrechtKernel

Hierarchy

TPersistent

|

TCustomKernel

|

TWindowedSincKernel

Description

A sinc kernel constrained by Albrecht window functions.
Those special window functions are used in spectral analysis to reduce the effect of spectral leakage. Windows with low sidelobe amplitude are necessary for the detection of small signals when highly dynamic spectra are concerned. For further details see: "A FAMILY OF COSINE-SUM WINDOWS FOR HIGH-RESOLUTION MEASUREMENTS" by Hans-Helge Albrecht

Reference

Methods | Properties
In TAlbrechtKernel:
 | Terms
In TWindowedSincKernel:
Create | Width
Filter |
GetWidth |
SetWidth |
In TCustomKernel:
Changed | Observer
RangeCheck |

See Also

Examples


Terms

TAlbrechtKernel.Terms

property Terms: Integer;

Description

Terms is the number of cosine terms used by the window. In case of terms = 2 the result is an optimized Hamming/Hanning window. The next step terms = 3 will result in an optimized blackman window. If you push terms to the max (= 11) you will have a smoothed, but pixelized result.


TBitmap32Resampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TCustomResampler

Description

TBitmap32Resampler is an abstract ancestor for bitmap resampling classes. A resampler is used for resizing bitmaps and for reconstructing color samples from a rasterized image.

This class is instantiated with one associated bitmap. This bitmap is always used when reconstructing a sample using the GetSample method.

For further information about resampling, see the Sampling and Rasterization topic.

Reference

Fields | Methods | Properties | Events
In TBitmap32Resampler:
 | Changed | Bitmap |
 | Create | PixelAccessMode |
 | GetSampleBounds | TransformerClass |
 | HasBounds |  |
 | PrepareSampling |  |
In TCustomResampler:
 | Resample | Width |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSample |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Destroy |  |
 | EndUpdate |  |

See Also

Examples, Sampling and Rasterization


Changed

TBitmap32Resampler.Changed

procedure Changed;

Description

Notifies the associated TBitmap32 instance that a property has changed and calls the inherited Changed method.


Create

TBitmap32Resampler.Create

constructor Create(ABitmap: TBitmap32); reintroduce; virtual;

Description

Creates and initializes an instance of TBitmap32Resampler.

After calling the inherited constructor, Create initializes the following properties:

  • Bitmap to Bitmap;
  • PixelAccessMode to pamSafe;
  • TransformerClass to TTransformer;

See Also

Bitmap, PixelAccessMode, TBitmap32Resampler, TransformerClass, TTransformer


GetSampleBounds

TBitmap32Resampler.GetSampleBounds

function GetSampleBounds: TRect; override;

Description

The GetSampleBounds method returns the ClipRect property of the associated bitmap instance.


HasBounds

TBitmap32Resampler.HasBounds

function HasBounds: Boolean; override;

Description

For TBitmap32Resampler descendants HasBounds always returns true, indicating that the sampling is constrained to the ClipRect property of the associated bitmap.

See Also

TBitmap32Resampler


PrepareSampling

TBitmap32Resampler.PrepareSampling

procedure PrepareSampling; override;

Description

The PrepareSampling method should be called before calling GetSample. See TCustomSampler.PrepareSampling for further details.

See Also

TCustomSampler.PrepareSampling


Bitmap

TBitmap32Resampler.Bitmap

property Bitmap: TBitmap32;

Description

Any instance of a TBitmap32Resampler descendant is associated with a bitmap. The Resample method is used whenever TCustomBitmap32.Draw or TCustomBitmap32.DrawTo is invoked. The GetSample method allows the resampler to reconstruct a single color sample from the bitmap.

See Also

_body, TCustomBitmap32.Draw, TCustomBitmap32.DrawTo, TCustomSampler.GetSample, TBitmap32, TCustomResampler


PixelAccessMode

TBitmap32Resampler.PixelAccessMode

property PixelAccessMode: TPixelAccessMode;

Description

Determines how pixels are accessed. See TPixelAccessMode for details.

See Also

TPixelAccessMode


TransformerClass

TBitmap32Resampler.TransformerClass

property TransformerClass: TTransformerClass;

Description

Each resampler is associated with a default transformer class.


TBlackmanKernel

Hierarchy

TPersistent

|

TCustomKernel

|

TWindowedSincKernel

Description

A sinc kernel constrained by a Blackman window function.

Reference

Methods | Properties
In TWindowedSincKernel:
Create | Width
Filter |
GetWidth |
SetWidth |
In TCustomKernel:
Changed | Observer
RangeCheck |

See Also

Examples


TBoxKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

TBoxKernel is one of the simplest and most fundamental kernels. Convolving with this kernel corresponds to the same approach used within nearest neighbor interpolation. The filter is defined as

and it is commonly known as a box filter, top-hat function or a Fourier window.

Reference

Methods | Properties
In TBoxKernel:
Filter |
GetWidth |
In TCustomKernel:
Changed | Observer
Create |
RangeCheck |

See Also

Examples


Filter

TBoxKernel.Filter

function Filter(Value: Single): Single; override;

Description

Returns the function value of this kernel given its input parameter.


GetWidth

TBoxKernel.GetWidth

function GetWidth: Single; override;

Description

Returns the width of this kernel.


TContracter

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

|

TKernelSampler

Description

This can be thought of as the inverse to the expand operation. The output for a sample coordinate (s, t) is given by

where f is a sampler and b is a structuring element. The structuring element is defined by the Kernel property of the class. See topic about Sampling and Rasterization for more info.

Reference

Fields | Methods | Properties | Events
In TContracter:
 | GetSample |  |
 | PrepareSampling |  |
In TKernelSampler:
 | Create | CenterX |
 | Destroy | CenterY |
 |  | Kernel |
In TNestedSampler:
 |  | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSampleBounds |  |
 | HasBounds |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

Sampling and Rasterization, TExpander


GetSample

TContracter.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


PrepareSampling

TContracter.PrepareSampling

procedure PrepareSampling; override;

Description

The PrepareSampling method should be called before calling GetSample. See TCustomSampler.PrepareSampling for further details.

See Also

TCustomSampler.PrepareSampling


TConvolver

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

|

TKernelSampler

Description

TConvolver provides functionality for performing discrete convolution within a chain of nested samplers. It will collect samples from its associated nested sampler within the region defined by the Kernel property.

Reference

Methods | Properties | Events
In TKernelSampler:
Create | CenterX |
Destroy | CenterY |
GetSample | Kernel |
In TNestedSampler:
 | Sampler |
In TCustomSampler:
FinalizeSampling |  |
GetSampleBounds |  |
HasBounds |  |
PrepareSampling |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
EndUpdate |  |


TCosineKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

The TCosineKernel class implements a cosine reconstruction filter.

Reference

Methods | Properties
In TCosineKernel:
Filter |
GetWidth |
In TCustomKernel:
Changed | Observer
Create |
RangeCheck |

See Also

Examples


Filter

TCosineKernel.Filter

procedure Filter: Single; override;

Description

Returns the function value of this kernel given its input parameter.


GetWidth

TCosineKernel.GetWidth

function GetWidth: Single; override;

Description

Returns the width of this kernel.


TCubicKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

This class implements a reconstruction filter described by a cubic polynomial. The formula for the filter is

Cubic filtering is used commonly for high-quality resampling.

Reference

Methods | Properties
In TCubicKernel:
Create | Coeff
Filter |
GetWidth |
RangeCheck |
In TCustomKernel:
Changed | Observer

See Also

Examples


Create

TCubicKernel.Create

constructor Create; override;

Description

Creates and instantiates a TCubicKernel object. The Coeff property is initialized to -0.5.

See Also

Coeff, TCubicKernel


Filter

TCubicKernel.Filter

function Filter(Value: Single): Single; override;

Description

Returns the function value of this kernel given its input parameter.


GetWidth

TCubicKernel.GetWidth

function GetWidth: Single; override;

Description

Returns the width of this kernel.


RangeCheck

TCubicKernel.RangeCheck

function RangeCheck: Boolean; override;

Description

Indicates whether or not this kernel needs range-checking.


Coeff

TCubicKernel.Coeff

property Coeff: Single;

Description

This is a coefficient of the cubic polynomial described by this kernel. See TCubicKernel description for details.

See Also

TCubicKernel


TCustomKernel

Hierarchy

TPersistent

Description

The TCustomKernel class is an ancestor class for reconstruction filters.

A reconstruction filter is used when resampling discretized data (for example, when resizing an image).

Reference

Methods | Properties
In TCustomKernel:
Changed | Observer
Create |
Filter |
GetWidth |
RangeCheck |

See Also

Examples


Changed

TCustomKernel.Changed

procedure Changed;

Description

Changed is called when a property is changed; this will also cause the Observer property to be notified.

See Also

Observer


Create

TCustomKernel.Create

procedure Create; virtual;

Description

Create will instantiate a TCustomKernel object.

See Also

TCustomKernel


Filter

TCustomKernel.Filter

function Filter: Single; virtual; abstract;

Description

Returns the function value of this kernel given its input parameter. Descendants should override this function.


GetWidth

TCustomKernel.GetWidth

function GetWidth: Single; override;

Description

Returns the width of this kernel.


RangeCheck

TCustomKernel.RangeCheck

function RangeCheck: Single; override;

Description

Descendants should override this procedure if the Kernels require range-checking of the final convolved result. Typically this is needed for kernels with negative lobes.


Observer

TCustomKernel.Observer

property Observer: TNotifiablePersistent;

Description

The Observer property is a class that will be notified of any changes to the properties of the kernel (by a change notification).

See Also

TNotifiablePersistent


TDilater

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

|

TKernelSampler

|

TMorphologicalSampler

Description

TDilater is a nested sampler for performing morphological dilation. This operation is defined as

where f is a sampler and b is a structuring element. By performing morphological dilation, high intensity image features will become expanded. This is the opposite effect to morphological dilation. The structuring element is defined by the Kernel property of the class. See topic about Sampling and Rasterization for more info.

Reference

Fields | Methods | Properties | Events
In TKernelSampler:
 | Create | CenterX |
 | Destroy | CenterY |
 | GetSample | Kernel |
In TNestedSampler:
 |  | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSampleBounds |  |
 | HasBounds |  |
 | PrepareSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

Sampling and Rasterization, TDilater


TDraftResampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TCustomResampler

|

TBitmap32Resampler

|

TLinearResampler

Description

This class implements an algorithm for fast downsampling. The result is better than nearest neighbor interpolation, but it is not quite as good as linear resampling. Fast downsampling is very useful for generation of thumbnail images.

For upsampling the same method is used as in TLinearResampler.

Reference

Fields | Methods | Properties | Events
In TLinearResampler:
 | Create |  |
 | Destroy |  |
 | GetSample |  |
 | PrepareSampling |  |
In TBitmap32Resampler:
 | Changed | Bitmap |
 | GetSampleBounds | PixelAccessMode |
 | HasBounds | TransformerClass |
In TCustomResampler:
 | Resample | Width |
In TCustomSampler:
 | FinalizeSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | EndUpdate |  |

See Also

Examples, TLinearResampler


TEroder

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

|

TKernelSampler

|

TMorphologicalSampler

Description

TEroder is a nested sampler for performing morphological erosion. This operation is defined as

where f is a sampler and b is a structuring element. Unlike dilation, which expands the image features, erosion will cause the high intensity image features to become thinner. The structuring element is defined by the Kernel property of the class. See topic about Sampling and Rasterization for more info.

Reference

Fields | Methods | Properties | Events
In TEroder:
 | Create |  |
In TKernelSampler:
 | Destroy | CenterX |
 | GetSample | CenterY |
 |  | Kernel |
In TNestedSampler:
 |  | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSampleBounds |  |
 | HasBounds |  |
 | PrepareSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

Examples, Sampling and Rasterization, TDilater


Create

TEroder.Create

constructor Create(ASampler: TCustomSampler); override;

Description

Creates and instantiates a TEroder object.


TExpander

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

|

TKernelSampler

Description

TExpander implements a neighborhood operation similar to morphological dilation. However, unlike ordinary dilation, where the structuring element is added to the color samples, the expand operation will multiply the weights. We define this operator as

where f is a sampler and b is a structuring element. The structuring element is defined by the Kernel property of the class. See topic about Sampling and Rasterization for more info.

Reference

Fields | Methods | Properties | Events
In TKernelSampler:
 | Create | CenterX |
 | Destroy | CenterY |
 | GetSample | Kernel |
In TNestedSampler:
 |  | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSampleBounds |  |
 | HasBounds |  |
 | PrepareSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

Sampling and Rasterization, TDilater


TGaussianKernel

Hierarchy

TPersistent

|

TCustomKernel

|

TWindowedSincKernel

Description

This class implements a Sinc filter constrained by a Gaussian window function.

Reference

Methods | Properties
In TGaussianKernel:
Create | Sigma
In TWindowedSincKernel:
Filter | Width
GetWidth |
SetWidth |
In TCustomKernel:
Changed | Observer
RangeCheck |

See Also

Examples


Create

TGaussianKernel.Create

constructor Create; override;

Description

A brief description of Create.


Sigma

TGaussianKernel.Sigma

property Sigma: Single;

Description

Sigma is a parameter of the gaussian window.


THammingKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

This class implements a Sinc filter constrained by the Hamming window function.

Reference

Methods | Properties
In TCustomKernel:
Changed | Observer
Create |
Filter |
GetWidth |
RangeCheck |

See Also

Examples


THannKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

This class implements a Sinc filter constrained by the Hann window function.

Reference

Methods | Properties
In TCustomKernel:
Changed | Observer
Create |
Filter |
GetWidth |
RangeCheck |

See Also

Examples


THermiteKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

An implementation of the hermite kernel, including Bias and Tension parameters.

Reference

Fields | Methods | Properties
In THermiteKernel:
 | Create | Bias
 | Filter | Tension
 | GetWidth |
 | RangeCheck |
In TCustomKernel:
 | Changed | Observer

See Also

Examples


Create

THermiteKernel.Create

constructor Create; override;

Description

Call create to instantiate a THermiteKernel object.

Upon creation the properties initialized by setting

  • Bias to 0;
  • Tension to 0.

See Also

Bias, Tension, THermiteKernel


Filter

THermiteKernel.Filter

function Filter(Value: Single): Single; override;

Description

Returns the function value of this kernel given its input parameter.


GetWidth

THermiteKernel.GetWidth

function GetWidth: Single; override;

Description

Returns the width of this kernel.


RangeCheck

THermiteKernel.RangeCheck

function RangeCheck: Boolean; override;

Description

Indicates whether or not this kernel needs range-checking.


Bias

THermiteKernel.Bias

property Bias: Single;

Description

The Bias property will affect the left-right alignment of the kernel function.


Tension

THermiteKernel.Tension

property Tension: Single;

Description

The tension parameter will influence the smoothness of the curve.


TKernelResampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TCustomResampler

|

TBitmap32Resampler

Description

TKernelResampler is a general class for image resampling using arbitrary convolution filters. It implements a fast method for resizing images, by precomputing kernel weights in mapping tables or coefficient bins.

For single-sample look-ups, the GetSample method supports three different kernel modes:

  • kmDynamic — kernel weights are computed on-the-fly;
  • kmTableNearest — kernel weights are stored in a table, nearest-neighbor is used for the look-up;
  • kmTableLinear — same as above, but uses linear interpolation for the look-up.

For further information, see topic about Sampling and Rasterization.

Reference

Fields | Methods | Properties | Events
In TKernelResampler:
 | Create | Kernel |
 | Destroy | KernelClassName |
 | FinalizeSampling | KernelMode |
 | GetSample | TableSize |
 | PrepareSampling |  |
In TBitmap32Resampler:
 | Changed | Bitmap |
 | GetSampleBounds | PixelAccessMode |
 | HasBounds | TransformerClass |
In TCustomResampler:
 | Resample | Width |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | EndUpdate |  |

See Also

Examples, Sampling and Rasterization


Create

TKernelResampler.Create

constructor Create(Bitmap: TBitmap32); override;

Description

Call Create to construct a new TKernelResampler instance.

After calling the inherited constructor, the following properties are set:

  • TableSize is set to 32;
  • Kernel is set to TNearestKernel;

See Also

_BODY, TBoxKernel


Destroy

TKernelResampler.Destroy

destructor Destroy; override;

Description

Destroys the resampler object and frees all associated memory.

Do not call Destroy directly, use Free instead.


FinalizeSampling

TKernelResampler.FinalizeSampling

procedure FinalizeSampling; override;

Description

The FinalizeSampling method should be paired with PrepareSampling. It is called when the sampling is finished. See TCustomSampler.FinalizeSampling for further details.

See Also

TCustomSampler.FinalizeSampling, TCustomSampler.PrepareSampling


GetSample

TKernelResampler.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


PrepareSampling

TKernelResampler.PrepareSampling

procedure PrepareSampling; override;

Description

The PrepareSampling method should be called before calling GetSample. See TCustomSampler.PrepareSampling for further details.

See Also

TCustomSampler.PrepareSampling


Kernel

TKernelResampler.Kernel

property Kernel: TCustomKernel;

Description

This property specifies which kernel is used for performing resampling. Samples are reconstructed through convolution with this kernel.

See Also

TCustomKernel


KernelClassName

TKernelResampler.KernelClassName

property KernelClassName: string;

Description

KernelClassName specifies the class name of the current associated kernel. It should never be changed at run-time. It is only used by the object inspector at desging-time.


KernelMode

TKernelResampler.KernelMode

property KernelMode: TKernelMode;

Description

Describes the current kernel mode. See TKernelMode for details.

See Also

TKernelMode


TableSize

TKernelResampler.TableSize

property TableSize: Integer;

Description

TableSize determines the size of the table used in GetSample for kmTableNearest and kmTableLinear kernel modes.

For kmTableNearest the weightcurve of the kernels is quantized in proportional to the tablesize. Perceptually the side effect of the table nearest approach, becomes visible as the tablesize decreases. With a table size of 2, the actual result becomes similar to using the box kernel.

For kmTableLinear the weightcurve of the kernels is approximized via linear interpolation between the quantized values in the table. Perceptually the side effect of the table linear approach, becomes visible as the table size decreases. With a table size of 2, the actual result becomes similar to using the linear kernel.

See Also

GetSample, TBoxKernel, TKernelMode, TLinearKernel


TKernelSampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

Description

TKernelSampler is a base class for samplers that compute an output sample by collecting a number of samples in a local region of the actual sample coordinate. Subsamples are collected from a regular sampling grid by storing the sample

The size of the grid is equal to the size of the associated kernel. Descendants of this class should override the protected UpdateBuffer method.

Reference

Methods | Properties | Events
In TKernelSampler:
Create | CenterX |
Destroy | CenterY |
GetSample | Kernel |
In TNestedSampler:
 | Sampler |
In TCustomSampler:
FinalizeSampling |  |
GetSampleBounds |  |
HasBounds |  |
PrepareSampling |  |
In TNotifiablePersistent:
BeginUpdate | UpdateCount | OnChange
Changed |  |
EndUpdate |  |


Create

TKernelSampler.Create

constructor Create(ASampler: TCustomSampler); override;

Description

Creates and instantiates a TKernelSampler object.

See Also

TCustomKernel, TKernelSampler


Destroy

TKernelSampler.Destroy

destructor Destroy; override;

Description

Destroys the kernel sampler object and frees all associated memory.

Do not call Destroy directly, use Free method instead.


GetSample

TKernelSampler.GetSample

function GetSampleInt(X, Y: Integer): TColor32; override;

function GetSampleFixed(X, Y: TFixed): TColor32; override;

Description

Collects samples from the area defined by the kernel and invokes the UpdateBuffer for each new sample. When all samples have been processed, the buffer is converted into the TColor32 format using the protected ConvertBuffer method.

See TCustomSampler.GetSample for further details.

See Also

Color Types, TCustomSampler.GetSample, TFixed


CenterX

TKernelSampler.CenterX

property CenterX: Integer;

Description

CenterX determines the vertical position of the kernel relative to the sample as the UpdateBuffer method is applied.


CenterY

TKernelSampler.CenterY

property CenterY: Integer;

Description

CenterY determines the horizontal position of the kernel relative to the sample as the UpdateBuffer method is applied.


Kernel

TKernelSampler.Kernel

property Kernel: TIntegerMap;

Description

The kernel property is used for describing the convolution kernel (for convolution) and the structuring element (for morphological operations).


TLanczosKernel

Hierarchy

TPersistent

|

TCustomKernel

|

TWindowedSincKernel

Description

This class implements the Lanczos filter function. It uses the a single lobe of the sinc filter as a window.

Reference

Methods | Properties
In TWindowedSincKernel:
Create | Width
Filter |
GetWidth |
SetWidth |
In TCustomKernel:
Changed | Observer
RangeCheck |

See Also

Examples


TLinearKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

This class implements a linear reconstruction filter. Linear interpolation is a first-degree method that passes a straight line through every two consecutive points of the input signal.

The filter is described by the following interpolation kernel:

In literature h(x) is often referred to as a triangle filter, tent filter, roof function, Chateau function or a Bartlett window.

Reference

Methods | Properties
In TLinearKernel:
Filter |
GetWidth |
In TCustomKernel:
Changed | Observer
Create |
RangeCheck |

See Also

Examples


Filter

TLinearKernel.Filter

function Filter(Value: Single): Single; override;

Description

A brief description of Window.


GetWidth

TLinearKernel.GetWidth

function GetWidth: Single; override;

Description

Returns the width of this kernel.


TLinearResampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TCustomResampler

|

TBitmap32Resampler

Description

TLinearResampler implements a linear resampling algorithm. This algorithm is used only if the bounds of the destination bitmap is larger than the bounds of the source bitmap. Otherwise resampling is performed using the same method as in TKernelResampler.

Reference

Fields | Methods | Properties | Events
In TLinearResampler:
 | Create |  |
 | Destroy |  |
 | GetSample |  |
 | PrepareSampling |  |
In TBitmap32Resampler:
 | Changed | Bitmap |
 | GetSampleBounds | PixelAccessMode |
 | HasBounds | TransformerClass |
In TCustomResampler:
 | Resample | Width |
In TCustomSampler:
 | FinalizeSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | EndUpdate |  |

See Also

Examples, Examples, TKernelResampler


Create

TLinearResampler.Create

constructor Create(Bitmap: TBitmap32); override;

Description

A brief description of Window.

See Also

TBitmap32


Destroy

TLinearResampler.Destroy

destructor Destroy; override;

Description

Destroys the resampler object and frees all associated memory.

Do not call Destroy directly, use Free method instead.


GetSample

TLinearResampler.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


PrepareSampling

TLinearResampler.PrepareSampling

procedure PrepareSampling; override;

Description

The PrepareSampling method should be called before calling GetSample. See TCustomSampler.PrepareSampling for further details.

See Also

TCustomSampler.PrepareSampling


TMitchellKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

An implementation of a special case of the cubic filter described by Mitchell.

Reference

Fields | Methods | Properties
In TMitchellKernel:
 | Filter |
 | GetWidth |
 | RangeCheck |
In TCustomKernel:
 | Changed | Observer
 | Create |

See Also

Examples, Examples


Filter

TMitchellKernel.Filter

function Filter(Value: Single): Single; override;

Description

A brief description of Window.


GetWidth

TMitchellKernel.GetWidth

function GetWidth: Single; override;

Description

Returns the width of this kernel.


RangeCheck

TMitchellKernel.RangeCheck

function RangeCheck: Boolean; override;

Description

Indicates whether or not this kernel needs range-checking.


TMorphologicalSampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

|

TKernelSampler

Description

Abstract ancestor class for TDilater and TEroder. You should not instantiate this class itself.

Reference

Fields | Methods | Properties | Events
In TKernelSampler:
 | Create | CenterX |
 | Destroy | CenterY |
 | GetSample | Kernel |
In TNestedSampler:
 |  | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSampleBounds |  |
 | HasBounds |  |
 | PrepareSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

TEroder.Create, Examples, Examples, TDilater


TNearestResampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TCustomResampler

|

TBitmap32Resampler

Description

This class implements a fast resampling method based on the nearest neighbor interpolation algorithm.

Reference

Fields | Methods | Properties | Events
In TNearestResampler:
 | Create |  |
 | GetSample |  |
 | PrepareSampling |  |
In TBitmap32Resampler:
 | Changed | Bitmap |
 | GetSampleBounds | PixelAccessMode |
 | HasBounds | TransformerClass |
In TCustomResampler:
 | Resample | Width |
In TCustomSampler:
 | FinalizeSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Destroy |  |
 | EndUpdate |  |

See Also

Examples, Examples


Create

TNearestResampler.Create

constructor Create(ABitmap: TBitmap32); override;

Description

Create instantiates a TNearestResampler object by first calling the inherited constructor and then initializing the TransformerClass property to TNearestTransformer.

See Also

TBitmap32, TNearestResampler, TNearestTransformer, TBitmap32Resampler.TransformerClass


GetSample

TNearestResampler.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


PrepareSampling

TNearestResampler.PrepareSampling

procedure PrepareSampling; override;

Description

The PrepareSampling method should be called before calling GetSample. See TCustomSampler.PrepareSampling for further details.

See Also

TCustomSampler.PrepareSampling


TNearestTransformer

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

|

TTransformer

Description

Description

Reference

Fields | Methods | Properties | Events
In TNearestTransformer:
 | GetSample |  |
In TTransformer:
 | GetSampleBounds | Transformation |
 | HasBounds |  |
 | PrepareSampling |  |
In TNestedSampler:
 | Create | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Destroy |  |
 | EndUpdate |  |

See Also

Examples, Examples


GetSample

TNearestTransformer.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


TNestedSampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

Description

TNestedSampler is a base class for chained or nested samplers. Descendants of TNestedSampler should provide sampling methods that rely on the use of another sampler. This nested sampling mechanism can be used beneficially when implementing super samplers or samplers that transform coordinates or perform other intermediate sampling operations.

See the topic about Sampling and Rasterization for additional information.

Reference

Fields | Methods | Properties | Events
In TNestedSampler:
 | Create | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSample |  |
 | GetSampleBounds |  |
 | HasBounds |  |
 | PrepareSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Destroy |  |
 | EndUpdate |  |

See Also

Sampling and Rasterization, TNestedSampler


Create

TNestedSampler.Create

procedure Create(Sampler: TCustomSampler); override;

Description

Creates and initializes an instance of TNesetSampler.

Sampler is an instance of TCustomSampler used by descendants to retrieve samples in a nested fashion.

See Also

_BODY, TNestedSampler


Sampler

TNestedSampler.Sampler

property Sampler: TCustomSampler;

Description

When the TNestedSampler class is instantiated, it requires a separate sampler to forward samples to its own particular GetSample implementation. Thus it is essential that this property is properly set up to point to another sampler (circular references must also be avoided).

See Also

_body, TCustomSampler.GetSample, TCustomSampler


TPatternSampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

Description

TPatternSampler provides a mechanism for performing sampling according to a preinitialize sample pattern. This pattern is implemented as a matrix of TArrayOfFixedPoint. Each pixel in the rasterized output bitmap will have a designated set of sampling points specified by wrapping this sample pattern across the image.

Reference

Fields | Methods | Properties | Events
In TPatternSampler:
 | Destroy | Pattern |
 | GetSample |  |
In TNestedSampler:
 | Create | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSampleBounds |  |
 | HasBounds |  |
 | PrepareSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

Examples, Point Types, Examples


Destroy

TPatternSampler.Destroy

procedure Destroy; override;

Description

Destroys the kernel object and frees all associated memory.

Do not call Destroy directly, use Free method instead.


GetSample

TPatternSampler.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


Pattern

TPatternSampler.Pattern

property Pattern: TFixedSamplePattern;

type
TFixedSamplePattern = array of array of TArrayOfFixedPoint;

Description

Pattern is a two-dimensional array of TArrayOfFixedPoint. Pixels are super-sampled by collecting sub-samples for each sample coordinate specified in one of the elements of the Pattern. For irregular sampling it is useful to use tiles of irregularly generated samples, since this will reduce aliasing. Thus, the sample pattern can be varied from pixel to pixel by adjusting the size of the Pattern matrix. This will cause the sample pattern to be repeated.

See Also

Point Types


TSelectiveConvolver

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

|

TKernelSampler

|

TConvolver

Description

TSelectiveConvolver works similarly to TConvolver, but it will exclude color samples from the convolution depending on a the difference from a local reference sample value. This way we may for instance perform smoothing for regions with small color variance, while still maintaining the high contrast features of the image.

Reference

Fields | Methods | Properties | Events
In TSelectiveConvolver:
 | Create | Delta |
 | GetSample |  |
In TKernelSampler:
 | Destroy | CenterX |
 |  | CenterY |
 |  | Kernel |
In TNestedSampler:
 |  | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSampleBounds |  |
 | HasBounds |  |
 | PrepareSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | EndUpdate |  |

See Also

Examples, Examples, TConvolver


Create

TSelectiveConvolver.Create

constuctor Create(ASampler: TCustomSampler); override;

Description

Create instantiates an TSelectiveConvolver object and then sets Delta to 30.

See Also

Delta, TSelectiveConvolver


GetSample

TSelectiveConvolver.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


Delta

TSelectiveConvolver.Delta

property Delta: Single;

Description

Selective convolution requires a Delta parameter for determining which color samples should be included in the convolution. For each sample location one reference sample C is chosen. Color samples that are not within the threshold range [C - Delta, C + Delta], will be excluded from the convolution.


TSinshKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

The sinsh kernel is defined as

where alpha is a custom coefficient specified by the Coeff property.

Reference

Fields | Methods | Properties
In TSinshKernel:
 | Create | Coeff
 | Filter | Width
 | GetWidth |
 | SetWidth |
In TCustomKernel:
 | Changed | Observer
 | RangeCheck |

See Also

Examples, Examples


Create

TSinshKernel.Create

constructor Create; override;

Description

Creates and instantiates a TSinshKernel object.

After calling the inherited constructor the following properties are set:

  • Width is set to 3;
  • Coeff is set to 0.5.

See Also

Coeff, TSinshKernel, Width


Filter

TSinshKernel.Filter

function Filter: Single; override;

Description

Returns the function value of this kernel given its input parameter.


GetWidth

TSinshKernel.GetWidth

function GetWidth: Single; override;

Description

Returns the width of the kernel.


SetWidth

TSinshKernel.SetWidth

procedure SetWidth(Value: Single);

Description

TSinshKernel supports adjustment of the width of the kernel using SetWidth.


Coeff

TSinshKernel.Coeff

property Coeff: Single;

Description

The Coeff property determines the shape of the filter. The coefficient should be strictly positive; when it approaches zero, the curve will resemble the ideal sinc filter.


Width

TSinshKernel.Width

property Width: Single;

Description

Set and get the width of the sinsh kernel.


TSplineKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

This class implements a B-Spline interpolation filter.

Reference

Fields | Methods | Properties
In TSplineKernel:
 | Filter |
 | GetWidth |
In TCustomKernel:
 | Changed | Observer
 | Create |
 | RangeCheck |

See Also

Examples, Examples


Filter

TSplineKernel.Filter

function Filter: Single; override;

Description

Returns the function value of this kernel given its input parameter.


GetWidth

TSplineKernel.GetWidth

function GetWidth: Single; override;

Description

Returns the width of the kernel.


TSuperSampler

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

Description

TSuperSampler is a nested sampler that adds a mechanism for performing super sampling. By adding a super sampler to a chain of samplers, it is possible to increase the sampling density, which will improve the quality of the rasterized output image.

For each input sample (x, y), we find the subsamples by using a rectangular grid, regularly subdivided (according to SamplingX and SamplingY) within the region (x - 0.5, y - 0.5, x + 0.5, y + 0.5).

Reference

Fields | Methods | Properties | Events
In TSuperSampler:
 | Create | SamplingX |
 | GetSample | SamplingY |
In TNestedSampler:
 |  | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
 | GetSampleBounds |  |
 | HasBounds |  |
 | PrepareSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Destroy |  |
 | EndUpdate |  |

See Also

Examples, Examples


Create

TSuperSampler.Create

constructor Create(ASampler: TCustomSampler); override;

Description

Call Create to instantiate a new super sampler.

After the inherited constructor is called the SamplingX and SamplingY properties are set to 4.

See Also

SamplingX, SamplingY, TCustomSampler


GetSample

TSuperSampler.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


SamplingX

TSuperSampler.SamplingX

property SamplingX: Integer;

Description

This property determines the number of vertical gridlines.


SamplingY

TSuperSampler.SamplingY

procedure SamplingY;

Description

This property determines the number of horizontal gridlines.


TTransformer

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TCustomSampler

|

TNestedSampler

Description

A transformer is a special kind of nested sampler that will transform the sampling coordinates using a transformation defined by a TTransformation descendant.

The transformer is normally used internally by the Transform routine, but it also possible to set it up in an arbitrary chain of samplers.

Reference

Fields | Methods | Properties | Events
In TTransformer:
 | GetSample | Transformation |
 | GetSampleBounds |  |
 | HasBounds |  |
 | PrepareSampling |  |
In TNestedSampler:
 | Create | Sampler |
In TCustomSampler:
 | FinalizeSampling |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Destroy |  |
 | EndUpdate |  |

See Also

Examples, Examples, TTransformation


GetSample

TTransformer.GetSample

function GetSampleInt(X, Y: Integer): TColor32;

function GetSampleFixed(X, Y: TFixed): TColor32;

function GetSampleFloat(X, Y: Single): TColor32;

Description

GetSample provides a method for acquiring a color sample from the coordinate (X, Y). The sample may be generated by the sampler itself, or it may be acquired from a nested sampler. Descendants of TCustomSampler must always override at least one of GetSampleFixed or GetSampleFloat.

The different postfixes determines the precision of the input parameters (integer, fixed-point or floating-point).

See Also

Color Types, TCustomSampler, TFixed


GetSampleBounds

TTransformer.GetSampleBounds

function GetSampleBounds: TRect; override;

Description

Fetches the sample bounds of the next nested sampler and uses TTransformation.GetTransformedBounds to update it to the correct (transformed) output rectangle.

See Also

TTransformation.GetTransformedBounds


HasBounds

TTransformer.HasBounds

function HasBounds: Boolean;

Description

Returns true if the associated transformation supports the GetTransformedBounds method.

See Also

TTransformation.GetTransformedBounds


PrepareSampling

TTransformer.PrepareSampling

procedure PrepareSampling;

Description

The PrepareSampling method should be called before calling GetSample. See TCustomSampler.PrepareSampling for further details.

See Also

TCustomSampler.PrepareSampling


Transformation

TTransformer.Transformation

property Transformation: TTransformation;

Description

Transformation specifies which transformation should be used for transforming sample coordinates.

See Also

TTransformation


TWindowedSincKernel

Hierarchy

TPersistent

|

TCustomKernel

Description

Returns the value of the Sinc function constrained by a window function. Descendant classes override the Window method in order to implement a custom window function.

h(x) = Sinc(x) * Window(x);

Windowed Sinc filters are known for producing high quality resampled images. Ideal resampling corresponds to filtering an image with the ideal low-pass filter (i.e. a Sinc filter). This is computionally expensive, since the Sinc function has infinite extent. Hence a window function is used to constrain the filter.

See topic about Sampling and Rasterization for further information.

Reference

Fields | Methods | Properties
In TWindowedSincKernel:
 | Create | Width
 | Filter |
 | GetWidth |
 | SetWidth |
In TCustomKernel:
 | Changed | Observer
 | RangeCheck |

See Also

Examples, Examples, Sampling and Rasterization


Create

TWindowedSincKernel.Create

constructor Create; override;

Description

Call create to instantiate a TWindowedSincKernel object.

The Width property will be initialized to 3.

See Also

TWindowedSincKernel, Width


Filter

TWindowedSincKernel.Filter

function Filter(Value: Single): Single;

Description

Returns the function value of this kernel given its input parameter.


GetWidth

TWindowedSincKernel.GetWidth

function GetWidth; override;

Description

Returns the width of this kernel .


SetWidth

TWindowedSincKernel.SetWidth

procedure SetWidth(Value: Single);

Description

Sets the width of this kernel.


Width

TWindowedSincKernel.Width

property Width: Single;

Description

This property allows user-control of the width of the kernel. This will adjust the width of the windows implemented in descendant classes.


GR32_Transforms

GR32_Transforms.pas provides functions and classes for combining and transforming bitmap images and their fragments.

It also includes affine and pojective transformations of bitmaps.

Contents

Types | Classes | Routines | Constants
TFloatMatrix | TAffineTransformation | RasterizeTransformation | IdentityMatrix
 | TBloatTransformation | SetBorderTransparent |
 | TDisturbanceTransformation | Transform |
 | TFishEyeTransformation | TransformPoints |
 | TProjectiveTransformation |  |
 | TRemapTransformation |  |
 | TTransformation |  |
 | TTwirlTransformation |  |


TFloatMatrix

type TFloatMatrix = array [0..2, 0..2] of Single;

Description

A 3x3 transformation matrix used in affine transformations.

See Also

TAffineTransformation


RasterizeTransformation

procedure RasterizeTransformation(Vectormap: TVectormap; Transformation: TTransformation; DstRect: TRect; CombineMode: TVectorCombineMode = vcmAdd; CombineCallback: TVectorCombineEvent = nil);

Description

RasterizeTransformation provides a convenient TTransformation rendering/buffering system, meaning that other transformationclasses can be precalculated into the vector map.

The Transformation parameter is a reference to a descendant of an abstract TTransformation class. It specifies all necessary transformation parameters.

CombineMode is vcmAdd by default, and the transformation will be added to the existing vectors (note that the routine will handle the conversion to relative vector space). When combine mode is vcmReplace, transformation vectors will replace the existing ones in the vectormap. When combine mode is vcmCustom, the last parameter CombineCallback will be used. Note that even in vcmCustom mode, vectors will be made relative by RasterizeTransformation.

See Also

Rectangle Types, TRemapTransformation, TTransformation, TVectorCombineEvent, TVectorCombineMode, TVectorMap


SetBorderTransparent

procedure SetBorderTransparent(ABitmap: TCustomBitmap32; ARect: TRect);

Description

This is an auxiliary function that sets the alpha channel along the edges of specified rectangle to zero. It may be used on a bitmap before passing it to Transform function as a workarownd to the edge antialiasing problem. For a dynamic option see TPixelAccessMode pamTransparentEdge, which can do the same trick without any destructive editing.

See Also

TCustomBitmap32, TPixelAccessMode, Transform, Rectangle Types


Transform

procedure Transform(Dst, Src: TCustomBitmap32; Transformation: TTransformation);

Description

Transform is responsible for arbitrary geometrical transformations of bitmaps or their fragments. The current version supports only affine and projective transformations.

The Transformation parameter is a reference to a descendant of an abstract TTransformation class. It specifies all necessary transformation parameters.

When Src.StretchFilter is different from sfNearest, Transform uses bilinear interpolation for magnification (along any axis) as for minification, it is not as accurate as StretchTransfer function. If you need better quality when minimizing the bitmaps, transform them into the temporary buffer so that there is no minification invlolved, then StretchTransfer to a final bitmap.

The function does not support spline interpolation, if Src.StretchFilter is sfSpline, Transform operates as if it were sfLinear.

There is an issue with antialiasing and edges. How to make them antialiased and still keep the performance? The solution implemented in Graphics32 is similar to the one used in OpenGL. You just have to provide the source bitmap (or its region) with transparent edges. In the original image, you’ll have to force the alpha channel on its edges to zeroes, for example, using the SetBorderTransparent method.

Remember, that color is interpolated as well, it means that for nice fadeout the color on the border should match the color of pixels lying next to the border.

In case the bitmap is transformed in dmOpaque mode, it might be better to keep the color on the edge close to the color of the background.

See Also

SetBorderTransparent, TCustomBitmap32.StretchFilter, StretchTransfer, TAffineTransformation, TCustomBitmap32, TProjectiveTransformation, Examples, TTransformation


TransformPoints

function TransformPoints(Points: TArrayOfArrayOfFixedPoint; Transformation: TTransformation): TArrayOfArrayOfFixedPoint;

Description

Transforms all Points using the supplied Transformation instance and returns the new set of transformed points.

See Also

TTransformation


IdentityMatrix

const IdentityMatrix: TFloatMatrix =(
(1, 0, 0),
(0, 1, 0),
(0, 0, 1));

Description

An identity matrix, which is loaded in Matrix field of TAffineTransformation class when calling its Clear method.

See Also

TAffineTransformation.Clear, TAffineTransformation.Matrix, TAffineTransformation


TAffineTransformation

Hierarchy

TObject

|

TTransformation

Description

The transformation is defined by 3x3 homogeneous matrix of single-precision floats, TFloatMatrix:

Only the first two rows are used for coordinate transformation at the final stage.

Reference

Fields | Methods | Properties
In TAffineTransformation:
Matrix | Clear |
 | Create |
 | GetTransformedBounds |
 | Rotate |
 | Scale |
 | Skew |
 | Translate |
In TTransformation:
 | HasTransformedBounds | SrcRect
 | ReverseTransform |
 | Transform |

See Also

Examples, Examples, Examples, TFloatMatrix, Examples


Matrix

TAffineTransformation.Matrix

Matrix: TFloatMatrix;

Description

Stores the transformation matrix. The matrix is accessed as a field instead of a property in order to make it Borland C++ Builder compatible.

See Also

TFloatMatrix


Clear

TAffineTransformation.Clear

procedure Clear;

Description

Resets the transformation (loads IdentityMatrix into the Matrix field).

See Also

IdentityMatrix, Matrix


Create

TAffineTransformation.Create

constructor Create; virtual;

Description

Creates and initializes an instance of TAffineTransformation.

Upon creation, the Matrix field is initialized to IdentityMatrix.

See Also

IdentityMatrix, Matrix, TAffineTransformation


GetTransformedBounds

TAffineTransformation.GetTransformedBounds

function GetTransformedBounds: TRect; override;

Description

Returns the bounding rectangle that surrounds the destination area affected by the transformation. The coordinates of the rectangle are specified relative to the destination bitmap origin.

See Also

Rectangle Types


Rotate

TAffineTransformation.Rotate

procedure Rotate(Cx, Cy, Alpha: Single);

Description

At first, the origin is translated to (Cx, Cy) point, then the image is rotated around the origin by Alpha degrees

and finally, the origin is shifted back.


Scale

TAffineTransformation.Scale

procedure Scale(Sx, Sy: Single);

Description

Adds scale to the transformation:


Skew

TAffineTransformation.Skew

procedure Skew(Fx, Fy: Single);

Description

Adds the skew to the transformation:


Translate

TAffineTransformation.Translate

procedure Translate(Dx, Dy: Single);

Description

Translates the image:


TBloatTransformation

Hierarchy

TObject

|

TTransformation

Description

The bloat transformation class provides an adjustable type of lens distortion. Setting bloat power to a positive value gives a fisheye-like distortion, but with less spheric effect (as seen in the left image below). Setting the bloat power to a negative value will affect the transformation in the opposite way (as seen in the right image below).

Reference

Fields | Methods | Properties
In TBloatTransformation:
 |  | BloatPower
In TTransformation:
 | GetTransformedBounds | SrcRect
 | HasTransformedBounds |
 | ReverseTransform |
 | Transform |

See Also

TFishEyeTransformation


BloatPower

TBloatTransformation.BloatPower

property BloatPower: Single;

Description

BloatPower specifies the scaling of the bloat formula.


TDisturbanceTransformation

Hierarchy

TObject

|

TTransformation

Description

This transformation class implements a randomizing displacement. The scaling of the randomization can be controlled from the Disturbance property. The effect of the transformation is visualized in the following image:

Reference

Methods | Properties
In TDisturbanceTransformation:
 | Disturbance
In TTransformation:
GetTransformedBounds | SrcRect
HasTransformedBounds |
ReverseTransform |
Transform |


Disturbance

TDisturbanceTransformation.Disturbance

property Disturbance: Single;

Description

Disturbance specifies how extreme the random displacement will be scaled.


TFishEyeTransformation

Hierarchy

TObject

|

TTransformation

Description

The fisheye transformation implements a transformation similar to wideangle lens distortion ("fisheyes"). The effect of the transformation can be seen in the image below. For illustrative purposes the distortion were amplified by rasterizing the transformation to the vector map of TRemapTransformation and adjusting the scale factors of the latter.

Reference

Fields | Methods | Properties
In TTransformation:
 | GetTransformedBounds | SrcRect
 | HasTransformedBounds |
 | ReverseTransform |
 | Transform |

See Also

RasterizeTransformation, TRemapTransformation.Scale, TRemapTransformation


TProjectiveTransformation

Hierarchy

TObject

|

TTransformation

Description

This class specifies an arbitrary projective transformation. It transforms a rectangle from the source image into quadrilateral, defined by 4 points:

Note, that the destination quadrilateral has to be convex, otherwise the result is not specified.

Reference

Methods | Properties
In TProjectiveTransformation:
GetTransformedBounds | X0
 | X1
 | X2
 | X3
 | Y0
 | Y1
 | Y2
 | Y3
In TTransformation:
HasTransformedBounds | SrcRect
ReverseTransform |
Transform |

See Also

Examples


GetTransformedBounds

TProjectiveTransformation.GetTransformedBounds

function GetTransformedBounds: TRect; override;

Description

Returns the bounding rectangle that surrounds the destination area affected by the transformation. The coordinates of the rectangle are specified relative to the destination bitmap origin.

See Also

Rectangle Types


X0

TProjectiveTransformation.X0

property X0: Single;

Description

Specifies destination coordinate of the top-left point of the source rectangle.


X1

TProjectiveTransformation.X1

property X1: Single;

Description

Specifies destination coordinate of the top-right point of the source rectangle.


X2

TProjectiveTransformation.X2

property X2: Single;

Description

Specifies destination coordinate of the bottom-right point of the source rectangle.


X3

TProjectiveTransformation.X3

property X3: Single;

Description

Specifies destination coordinate of the bottom-left point of the source rectangle.


Y0

TProjectiveTransformation.Y0

property Y0: Single;

Description

Specifies destination coordinate of the top-left point of the source rectangle.


Y1

TProjectiveTransformation.Y1

property Y0: Single;

Description

Specifies destination coordinate of the top-right point of the source rectangle.


Y2

TProjectiveTransformation.Y2

propertyY2: Single;

Description

Specifies destination coordinate of the bottom-right point of the source rectangle.


Y3

TProjectiveTransformation.Y3

property Y3: Single;

Description

Specifies destination coordinate of the bottom-left point of the source rectangle.


TRemapTransformation

Hierarchy

TObject

|

TTransformation

Description

This TTransformation wraps TVectormap and implements a set of properties to control how the transformation uses the vectors of TVectormap in its transformation procedures.

The class itself will not provide any significant transformation algorithm: the subordinate vector map needs to be precalculated. The auxiliary routine RasterizeTransformation is useful for this purpose.

Reference

Fields | Methods | Properties
In TRemapTransformation:
 | GetTransformedBounds | MappingRect
 | HasTransformedBounds | Offset
 | Scale |
In TTransformation:
 | ReverseTransform | SrcRect
 | Transform |

See Also

Examples, RasterizeTransformation, TVectorMap


GetTransformedBounds

TRemapTransformation.GetTransformedBounds

function GetTransformedBounds: TRect; override;

Description

TRemapTransformation does not support transformed bounds retrieval. This can be determined calling HasTransformedBounds. However if called anyway, it returns Rect(-MaxInt, -MaxInt, MaxInt, MaxInt). The reason is that the transformed bounds cannot be predicted without transforming each vector in the vector map (an extreme overhead in performance), so the absolute most extreme transformed bounds will be returned.

See Also

HasTransformedBounds, Rectangle Types


HasTransformedBounds

TRemapTransformation.HasTransformedBounds

function HasTransformedBounds: Boolean; override;

Description

Returns false. For details see GetTransformedBounds

See Also

GetTransformedBounds


Scale

TRemapTransformation.Scale

procedure Scale(Sx: Single; Sy: Single);

Description

Scale stores internal scaling values, which multiplies the vectors when performing the transformation. If Sx = 0 and Sy = 0, no transformation will appear. Setting scaling values will not change the subordinate vectormap, it is applied in the actual transform procedure. The image warping example shows what effect scaling has.

See Also

Examples, MappingRect, Offset


MappingRect

TRemapTransformation.MappingRect

property MappingRect: TFloatRect;

Description

MappingRect specifies the scaling and positioning of the input coordinate space in conjunction with the usage of the subordinate vector map. I.e. changing the mapping rectangle will change the mapping onto the transformed space. Consider the following two images:

Here a fisheye transformation was rasterized centered on the subordinate vector map (using RasterizeTransformation). In the left image, the mapping rectangle (the red rubberband layer) is centered and shrinked somewhat. In the right image, the rectangle was changed to another position and scaled, causing a different mapping. The rasterized transformation has not been changed.

As seen above, the the mapping rectangle is not behaving like a transformed bounds rectangle. Thus for intuitive user interface, one may prefer another type of representation. The above representation is solely chosen for the sake of explanatory value.

See Also

GetTransformedBounds, Offset, RasterizeTransformation, Scale, Rectangle Types, TRubberbandLayer


Offset

TRemapTransformation.Offset

property Offset: TFloatVector;

Description

Offset specifies an offset applied to the transformation vectors during transform. Setting offset will not change the subordinate vectormap, it is applied in the actual transform procedure.

See Also

MappingRect, Scale, Vector Types


TTransformation

Hierarchy

TObject

Description

TTransformation is an abstract ancestor for bitmap transformation classes. TTransformation objects are passed as parameter in the Transform function, which actually performs the bitmap transformation. Custom decendants must at least implement ReverseTransformFloat (and TransformFloat, if forward transformation is supported), since this is the top precision level in the transformation system of Graphics32. All decendants must override at least this level, but for optimal performance, it is recommended that the integer and fixed versions are implemented, respectively.

Reference

Fields | Methods | Properties
In TTransformation:
 | GetTransformedBounds | SrcRect
 | HasTransformedBounds |
 | ReverseTransform |
 | Transform |

See Also

TAffineTransformation, Transform, TTransformation


GetTransformedBounds

TTransformation.GetTransformedBounds

function GetTransformedBounds: TRect; virtual; abstract;

Description

Returns the bounding rectangle that surrounds the destination area affected by the transformation. The coordinates of the rectangle are specified relative to the destination bitmap origin. Not all derived transformation types may be able to specify transformed bounds. In that case, the source rectangle is returned.

See Also

HasTransformedBounds, Rectangle Types


HasTransformedBounds

TTransformation.HasTransformedBounds

function HasTransformedBounds: Boolean;

Description

Returns true if a given derived transformation can specify its transformed bounds, otherwise the result is false. If custom decendants cannot specify transformed bounds, this method must be overridden, since the default result is true.

See Also

GetTransformedBounds


ReverseTransform

TTransformation.ReverseTransform

function ReverseTransform(const P: TPoint): TPoint; overload; virtual;

function ReverseTransform(const P: TFixedPoint): TFixedPoint; overload; virtual;

function ReverseTransform(const P: TFloatPoint): TFloatPoint; overload; virtual;

Description

Reverse-transforms the supplied point P and returns the result.


Transform

TTransformation.Transform

function Transform(const P: TPoint): TPoint; overload; virtual;

function Transform(const P: TFixedPoint): TFixedPoint; overload; virtual;

function Transform(const P: TFloatPoint): TFloatPoint; overload; virtual;

Description

Forward transforms the supplied point P and returns the result. Note that not all derived transformation classes supports forward transformation. If the given class do not support forward transformation an ETransformNotImplemented exception will be raised.


SrcRect

TTransformation.SrcRect

property SrcRect: TFloatRect;

Description

SrcRect specifies the boundary of the incoming image fragment.

Since it is a TFloatRect, the boundary has floating point coordinates.

See Also

Rectangle Types


TTwirlTransformation

Hierarchy

TObject

|

TTransformation

Description

This transformation class implements a twirl transformation. The amount of twirl can be controlled with the twirl property. The image below shows how a checkerboard pattern were transformed with this transformation. The twirl parameter were set very low for illustrative purposes. With high twirl frequencies (more extreme settings of the twirl property), it is recommended that antialiasing steps are taken (e.g. supersampling).

Reference

Methods | Properties
In TTwirlTransformation:
 | Twirl
In TTransformation:
GetTransformedBounds | SrcRect
HasTransformedBounds |
ReverseTransform |
Transform |


Twirl

TTwirlTransformation.Twirl

property Twirl: Single;

Description

Twirl controls the power of the twirl transformation. The parameter is rather sensitive, a realistic setting could e.g. be as low as 0.001. It is recommended that one experiments finding a useful range within a given enviroment, as no common range for the parameter can be specified.


GR32_VectorMaps

The GR32_VectorMaps.pas unit contains the TVectorMap class.

Contents

Types | Classes
TVectorCombineEvent | TVectorMap
TVectorCombineMode |
Vector Types |

See Also

TVectorMap


TVectorCombineEvent

type TVectorCombineEvent = procedure (F, P: TFixedVector; var B: TFixedVector) of object;

Desctiption

TVectorCombineEvent is a type for OnVectorCombine callback function, used in Merge, when VectorCombineMode is vcmCustom. It specifies a function which takes foreground vector (F) and mixes it with the background vector (B).

This function may optionally use progresson vector (P). The progression vector will by the merge routine be specified in the range X,Y: [-FIXEDONE..FIXEDONE], regardless of the specified source rect in Merge. This enables in-place masking of the vector map to be merged.

See Also

TVectorMap.Merge, TVectorMap.OnVectorCombine, Vector Types, TVectorMap.VectorCombineMode


TVectorCombineMode

type TVectorCombineMode = (vcmAdd, vcmReplace, vcmCustom);

Description

TVectorCombineMode defines how vectors will be combined (e.g. in TVectormap.Merge).

  • vcmAdd - Adds the source vectors.
  • vcmReplace - Replaces with source vectors.
  • vcmCustom - Uses a specified OnVectorCombine event.


Vector Types

Graphics32 currently uses a relative vector system, meaning that a vector have to be applied to a given absolute vector. The relative system propose a wider flexibility, but also a small overhead (the two additions needed). Future versions may introduce a relative/absolute distinction in relevant routines. To make a vector absolute, simply apply actual absolute vertices, but keep in mind that some implementations may expect relative vectors (e.g. TRemapTransformation.Vectormap uses relative vectors).

Vector types are defined with following structures:

TFloatVector

type TFloatVector = TFloatPoint;

type PFloatVector = ^TFloatVector;

Provides convenient naming, and compatibility with TFloatPoint.

TFixedVector

type TFloatVector = TFixedPoint;

type PFloatVector = ^TFloatVector;

Provides convenient naming, and compatibility with TFixedPoint.

TArrayOfFloatPoint

type TArrayOfFloatVector = array of TFloatVector;

type PArrayOfFloatVector = ^TArrayOfFloatVector;

A dynamic array of TFloatVector.

TArrayOfFixedPoint

type TArrayOfFixedVector = array of TFixedVector;

type PArrayOfFixedVector = ^TArrayOfFixedVector;

A dynamic array of TFixedVector.

See Also

Creating Points, TVectorMap


TVectorMap

Hierarchy

TPersistent

|

TNotifiablePersistent

|

TThreadPersistent

|

TCustomMap

Description

The TVectorMap class may be used to store two-dimensional vectors, and provides a set of useful indexing and interpolation properties. TVectorMap is an ancestor of TCustomMap and supports saving and loading (Photoshop .msh format). TRemapTransformation wraps TVectorMap, so for a TTransformation compatible implementation, this may be a better choice.

Reference

Fields | Methods | Properties | Events
In TVectorMap:
 | Clear | Vector | OnVectorCombine
 | Destroy | VectorCombineMode |
 | Empty | Vectors |
 | GetTrimmedBounds |  |
 | LoadFromFile |  |
 | Merge |  |
 | SaveToFile |  |
In TCustomMap:
 | Delete | Height | OnResize
 | Resized | Width |
 | SetSize |  |
In TThreadPersistent:
 | Lock | LockCount |
 | Unlock |  |
In TNotifiablePersistent:
 | BeginUpdate | UpdateCount | OnChange
 | Changed |  |
 | Create |  |
 | EndUpdate |  |

See Also

Examples, TCustomMap, TRemapTransformation, TTransformation, Vector Types, Examples


Clear

TVectorMap.Clear

procedure Clear;

Description

Fills the entire vectormap with zero vectors.


Destroy

TVectorMap.Destroy

destructor Destroy; override;

Description

Destroys the vectormap object and frees all the associated memory.

Do not call Destroy directly, use the Free method instead.


Empty

TVectorMap.Empty

function Empty: Boolean; override;

Description

Returns True if the vector map contains no data, that is Width or Height is equal to 0.

See Also

TCustomMap.Height, TCustomMap.Width


GetTrimmedBounds

TVectorMap.GetTrimmedBounds

function GetTrimmedBounds: TRect;

Description

Returns the smallest rectangle that surrounds non zero vectors in a vectormap. This is useful for optimizing heavy processing like supersampling by passing this rectangle as a clipping rectangle. Note that the procedure of analyzing a vectormap is rather expensive, thus carefully determine if the call is worth the cost.

See Also

Examples, Rectangle Types


LoadFromFile

TVectorMap.LoadFromFile

procedure LoadFromFile(const FileName: string);

Description

Loads a vector map from a file. Format supported is Photoshop .msh format, compatible with the Liquify plugin. See source for more details.

See Also

Examples, SaveToFile


Merge

TVectorMap.Merge

procedure Merge(DstLeft: Integer; DstTop: Integer; Src: TVectorMap; SrcRect: TRect);

Description

Merge provides a method for merging a vector map. VectorCombineMode specifies how the source vector map is merged. If VectorCombineMode is set to vcmCustom, OnVectorCombine will be used. The source parameter must not necessarily be some other vector map, so for example in-place masking or scaling is possible.

See Also

Rectangle Types, TVectorMap, VectorCombineMode


SaveToFile

TVectorMap.SaveToFile

procedure SaveToFile(const FileName: string);

Description

Writes a vector map to disk. Format supported is Photoshop .msh format, compatible with the Liquify plugin. See source for more details.

See Also

Examples, LoadFromFile


Vector

TVectorMap.Vector

property FixedVector[X, Y: Integer]: TFixedVector; default;

property FixedVectorS[X, Y: Integer]: TFixedVector;

property FixedVectorX[X, Y: TFixed]: TFixedVector;

property FixedVectorXS[X, Y: TFixed]: TFixedVector;

property FloatVector[X, Y: Integer]: TFloatVector;

property FloatVectorS[X, Y: Integer]: TFloatVector;

property FloatVectorF[X, Y: Single]: TFloatVector;

property FloatVectorFS[X, Y: Single]: TFloatVector;

Description

FixedVector property sets the value of the vector in the vectormap. Reading it, will return the vector value of the vector located at specified coordinates. This property does not validate the specified coordinates, so use it only when completely certain that the ranges provided is within the vectormap boundaries. FixedVector is declared as default property, you may use it as shown below:

Vectormap[10, 20] := Vectormap[20, 10]; // copy a vector from (20,10) to (10,20) position

FixedVectorS is a 'safe' version of the FixedVector property. When reading vectors from the outside the bitmap boundary, a vector of (0, 0) is returned. Writing with invalid coordinates will have no effect.

FixedVectorX provides a method for accessing the vectors in TFixed based coordinates. The returned vector is computed by performing linear interpolation on four adjacent vectors. Similarly, when vectors are set, they are distributed weighted over four adjacent vectors.

FixedVectorXS is a 'safe' version of the above property.

FloatVector/S/F/FS Provides floating point compatible versions of the above properties. Note that the floating point versions are provided for convenience only; coding for optimal performance, consider using fixedpoint versions (which will allow execution inside MMX enabled code segments). TVectormap stores its vectors natively in TFixedVector format, hence no extra precision is gained by using floating point versions.

See Also

Fixed Point Math, Naming Conventions, TFixed, Vector Types, Vector Types


VectorCombineMode

TVectorMap.VectorCombineMode

property VectorCombineMode: TVectorCombineMode;

Description

TVectorCombineMode determines the vector combine mode used in TVectormap.Merge.

See Also

TCombineMode


Vectors

TVectorMap.Vectors

property Vectors: PFixedPointArray;

Description

The read-only vectors property contains the address of the first (top-left) vector in a vectormap. If the vectormap is not allocated (width or height is zero), the returned address is nil.

Note, that numbering of rows in Graphics32 starts from the top-most one.

Data is continuously allocated in memory, row by row. You may safely access Width * Height elements, each of them is a 8-byte TFixedVector value.

See Also

TCustomBitmap32.Bits, TCustomMap.Height, Vector Types, TCustomMap.Width


OnVectorCombine

TVectorMap.OnVectorCombine

property OnVectorCombine: TVectorCombineEvent;

type TVectorCombineEvent = procedure (F, P: TFixedVector; var B: TFixedVector) of object;

Description

This event is called when vector map Merge is called in vcmCustom vector combine mode. Use this event to customize handling of vector combining. Note, however, that this event is called for every Vector in the map, so keeping the event handler small and fast is in your own interest.

See Also

Merge, TVectorCombineEvent, Vector Types, VectorCombineMode