Graphics Functions

Graphics Functions (GDI+)

The Graphics functions provide methods for drawing lines, curves, figures, images, and text. A Graphics object stores attributes of the display device and attributes of the items to be drawn.

Return Values

If the function succeeds, it returns Ok, which is an element of the Status enumeration.

If the function fails, it returns one of the other elements of the Status enumeration.

GdipSaveGraphics

Description

Saves the current state (transformations, clipping region, and quality settings) of this Graphics object. You can restore the state later by calling the GdipRestoreGraphics function.

Syntax

GpStatus WINGDIPAPI GdipSaveGraphics(

GpGraphics *graphics,

GraphicsState *state

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSaveGraphics ( _

BYVAL graphics AS DWORD, _

BYREF pState AS DWORD _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

state

[out] A value that identifies the saved state. Pass this value to the GdipRestoreGraphics function when you want to restore the state.

Remarks

When you call the GdipSaveGraphics function, an information block that holds the state of the Graphics object is put on a stack. The GdipSaveGraphics function returns a value that identifies that information block. When you pass the identifying value to the GdipRestoreGraphics function, the information block is removed from the stack and is used to restore the Graphics object to the state it was in at the time of the GdipSaveGraphics call. Note that the identifier returned by a given call to the GdipSaveGraphics function can be passed only once to the GdipRestoreGraphics function.

Calls to the GdipSaveGraphics function can be nested; that is, you can call the GdipSaveGraphics function several times before you call the GdipRestoreGraphics function. Each time you call the GdipSaveGraphics function, an information block is put on the stack, and you receive an identifier for the information block. When you pass one of those identifiers to the GdipRestoreGraphics function, the Graphics object is returned to the state it was in at the time of the GdipSaveGraphics call that returned that particular identifier. The information block placed on the stack by that GdipSaveGraphics call is removed from the stack, and all information blocks placed on that stack after that GdipSaveGraphics call are also removed.

Calls to the GdipBeginContainer function place information blocks on the same stack as calls to the GdipSaveGraphics function. Just as a GdipRestoreGraphics call is paired with a GdipSaveGraphics call, an GdipEndContainer call is paired with a GdipBeginContainer call.

Caution When you call GdipRestoreGraphics, all information blocks placed on the stack (by GdipSaveGraphics or by GdipBeginContainer) after the corresponding call to GdipSaveGraphics are removed from the stack. Likewise, When you call GdipEndContainer, all information blocks placed on the stack (by GdipSaveGraphics or by GdipBeginContainer) after the corresponding call to GdipBeginContainer are removed from the stack.

GdipScaleWorldTransform

Description

Updates this Graphics object's world transformation matrix with the product of itself and a scaling matrix.

Syntax

GpStatus WINGDIPAPI GdipScaleWorldTransform(

    GpGraphics *graphics,

    REAL sx,

    REAL sy,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipScaleWorldTransform ( _

    BYVAL graphics AS DWORD, _

    BYVAL sx AS SINGLE, _

    BYVAL sy AS SINGLE, _

    BYVAL order AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Simple precision value that specifies the horizontal scaling factor in the scaling matrix.

[in] Simple precision value that specifies the vertical scaling factor in the scaling matrix.

order

[in] Element of the MatrixOrder enumeration that specifies the order of multiplication. MatrixOrderPrepend specifies that the scaling matrix is on the left, and MatrixOrderAppend specifies that the scaling matrix is on the right. The default value is MatrixOrderPrepend.

GdipSetClipGraphics

Description

Updates the clipping region of this Graphics object to a region that is the combination of itself and the clipping region of another Graphics object.

Syntax

GpStatus WINGDIPAPI GdipSetClipGraphics(

    GpGraphics *graphics,

    GpGraphics *srcgraphics,

    CombineMode combineMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetClipGraphics ( _

    BYVAL graphics AS DWORD, _

    BYVAL srcgraphics AS LONG, _

    BYVAL combineMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

srcgraphics

[in] Pointer to a Graphics object that contains the clipping region to be combined with the clipping region of this Graphics object.

combinemode

[in] Element of the CombineMode enumeration that specifies how the specified region is combined with the clipping region of this Graphics object. The default value is CombineModeReplace.

GdipSetClipHrgn

Description

Updates the clipping region of this Graphics object to a region that is the combination of itself and a GDI region.

Syntax

GpStatus WINGDIPAPI GdipSetClipHrgn(

    GpGraphics *graphics,

    HRGN hRgn,

    CombineMode combineMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetClipHrgn ( _

    BYVAL graphics AS DWORD, _

    BYVAL hRgn AS DWORD, _

    BYVAL combineMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

hRgn

[in] Handle to a GDI region to be combined with the clipping region of this Graphics object. This is provided for legacy code. New applications should pass a Region object as the first parameter.

combinemode

[in] Element of the CombineMode enumeration that specifies how the specified region is combined with the clipping region of this Graphics object. The default value is CombineModeReplace.

Remarks

This function assumes that the GDI region specified by hRgn is already in device units, so it does not transform the coordinates of the GDI region.

GdipSetClipPath

Description

Updates the clipping region of this Graphics object to a region that is the combination of itself and the region specified by a graphics path. If a figure in the path is not closed, this method treats the nonclosed figure as if it were closed by a straight line that connects the figure's starting and ending points.

Syntax

GpStatus WINGDIPAPI GdipSetClipPath(

    GpGraphics *graphics,

    GpPath *path,

    CombineMode combineMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetClipPath ( _

  BYVAL graphics AS DWORD, _

    BYVAL path AS DWORD, _

    BYVAL combineMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

path

[in] Pointer to a GraphicsPath object that specifies the region to be combined with the clipping region of this Graphics object.

combinemode

[in] Element of the CombineMode enumeration that specifies how the specified region is combined with the clipping region of this Graphics object. The default value is CombineModeReplace.

Remarks

This function assumes that the GDI region specified by hRgn is already in device units, so it does not transform the coordinates of the GDI region.

GdipSetClipRect

Description

Updates the clipping region of this Graphics object to a region that is the combination of itself and a rectangle.

Syntax

GpStatus WINGDIPAPI GdipSetClipRect(

    GpGraphics *graphics,

    REAL x,

    REAL y,

    REAL width,

    REAL height,

    CombineMode combineMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetClipRect ( _

    BYVAL graphics AS DWORD, _

    BYVAL x AS SINGLE, _

    BYVAL y AS SINGLE, _

    BYVAL nWidth AS SINGLE, _

    BYVAL nHeight AS SINGLE, _

    BYVAL combineMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Simple precision value that specifies the x-coordinate of the rectangle to be combined with the clipping region of this Graphics object.

[in] Simple precision value that specifies the y-coordinate of the rectangle to be combined with the clipping region of this Graphics object.

width

[in] Simple precision value that specifies the width of the rectangle to be combined with the clipping region of this Graphics object.

height

[in] Simple precision value that specifies the height of the rectangle to be combined with the clipping region of this Graphics object.

combinemode

[in] Element of the CombineMode enumeration that specifies how the specified region is combined with the clipping region of this Graphics object. The default value is CombineModeReplace.

GdipSetClipRectI

Description

Updates the clipping region of this Graphics object to a region that is the combination of itself and a rectangle.

Syntax

GpStatus WINGDIPAPI GdipSetClipRectI(

    GpGraphics *graphics,

    INT x,

    INT y,

    INT width,

    INT height,

    CombineMode combineMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetClipRect ( _

    BYVAL graphics AS DWORD, _

    BYVAL x AS LONG, _

    BYVAL y AS LONG, _

    BYVAL nWidth AS LONG, _

    BYVAL nHeight AS LONG, _

    BYVAL combineMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Long integer value that specifies the x-coordinate of the rectangle to be combined with the clipping region of this Graphics object.

[in] Long integer value that specifies the y-coordinate of the rectangle to be combined with the clipping region of this Graphics object.

width

[in] Long integer value that specifies the width of the rectangle to be combined with the clipping region of this Graphics object.

height

[in] Long integer value that specifies the height of the rectangle to be combined with the clipping region of this Graphics object.

combinemode

[in] Element of the CombineMode enumeration that specifies how the specified region is combined with the clipping region of this Graphics object. The default value is CombineModeReplace.

GdipSetClipRegion

Description

Updates the clipping region of this Graphics object to a region that is the combination of itself and the region specified by a Region object.

Syntax

GpStatus WINGDIPAPI GdipSetClipRegion(

    GpGraphics *graphics,

    GpRegion *region,

    CombineMode combineMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetClipRegion ( _

    BYVAL graphics AS DWORD, _

    BYVAL region AS DWORD, _

    BYVAL combineMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

region

[in] Pointer to a Region object that specifies the region to be combined with the clipping region of this Graphics object.

combinemode

[in] Element of the CombineMode enumeration that specifies how the specified region is combined with the clipping region of this Graphics object. The default value is CombineModeReplace.

GdipSetCompositingMode

Description

Sets the compositing mode of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipSetCompositingMode(

GpGraphics *graphics,

CompositingMode compositingMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetCompositingMode ( _

BYVAL graphics AS DWORD, _

BYVAL compositingMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

compositingMode

[in] Element of the CompositingMode enumeration that specifies the compositing mode.

Remarks

Suppose you create a SolidBrush object based on a color that has an alpha component of 192, which is about 75 percent of 255. If your Graphics object has its compositing mode set to CompositingModeSourceOver, then areas filled with the solid brush are a blend that is 75 percent brush color and 25 percent background color. If your Graphics object has its compositing mode set to CompositingModeSourceCopy, then the background color is not blended with the brush color. However, the color rendered by the brush has an intensity that is 75 percent of what it would be if the alpha component were 255.

You cannot use CompositingModeSourceCopy along with TextRenderingHintClearTypeGridFit.

GdipSetCompositingQuality

Description

Sets the compositing quality of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipSetCompositingQuality(

GpGraphics *graphics,

CompositingQuality compositingQuality

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetCompositingQuality ( _

BYVAL graphics AS DWORD, _

BYVAL compositingQuality AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

compositingQuality

[in] Element of the CompositingQuality enumeration that specifies the compositing quality.

GdipSetInterpolationMode

Description

Sets the interpolation mode of this Graphics object. The interpolation mode determines the algorithm that is used when images are scaled or rotated.

Syntax

GpStatus WINGDIPAPI GdipSetInterpolationMode(

GpGraphics *graphics,

InterpolationMode interpolationMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetInterpolationMode ( _

BYVAL graphics AS DWORD, _

BYVAL interpolationMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

interpolationMode

[in] Element of the InterpolationMode enumeration that specifies the interpolation mode.

GdipSetMetafileDownLevelRasterizationLimit

Description

Sets the resolution for certain brush bitmaps that are stored in this metafile.

Syntax

GpStatus WINGDIPAPI GdipSetMetafileDownLevelRasterizationLimit(

GpMetafile * metafile,

UINT metafileRasterizationLimitDpi

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetMetafileDownLevelRasterizationLimit ( _

BYVAL metafile AS DWORD _

BYVAL MetafileRasterizationLimitDpi AS LONG _

) AS LONG

Parameters

metafile

[in] Pointer to the Metafile object.

metafileRasterizationLimitDpi

[in] Non-negative long integer value that specifies the resolution in dots per inch (dpi). If you set this parameter equal to 0, the resolution is set to match the resolution of the device context handle that was passed to the Metafile constructor. If you set this parameter to a value greater than 0 but less than 10, the resolution is left unchanged.

Remarks

The purpose of this method is to prevent metafiles from becoming too large as a result of texture and gradient brushes being stored at high resolution. Suppose you construct a Metafile object (for recording an EmfTypeEmfOnly metafile) based on the device context of a printer that has a resolution of 600 dpi. Also suppose you create a path gradient brush or a texture brush based on a Bitmap object that has a resolution of 96 dpi. If the bitmap that represents that brush is stored in the metafile with a resolution of 96 dpi, it will require much less space than if it is stored with a resolution of 600 dpi.

The default rasterization limit for metafiles is 96 dpi. So if you do not call this method at all, path gradient brush and texture brush bitmaps are stored with a resolution of 96 dpi.

The rasterization limit has an effect on metafiles of type EmfTypeEmfOnly and EmfTypeEmfPlusDual, but it has no effect on metafiles of type EmfTypeEmfPlusOnly.

GdipSetPageScale

Description

Sets the scaling factor for the page transformation of this Graphics object. The page transformation converts page coordinates to device coordinates.

Syntax

GpStatus WINGDIPAPI GdipSetPageScale(

GpGraphics *graphics,

REAL scale

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetPageScale ( _

BYVAL graphics AS DWORD, _

BYVAL pScale AS SINGLE _

) AS LONG

Parameters

metafile

[in] Pointer to the Metafile object.

scale

[in] Simple precision value that specifies the scaling factor.

GdipSetPageUnit

Description

Sets the unit of measure for this Graphics object. The page unit belongs to the page transformation, which converts page coordinates to device coordinates.

Syntax

GpStatus WINGDIPAPI GdipSetPageUnit(

GpGraphics *graphics,

GpUnit unit

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetPageUnit ( _

BYVAL graphics AS DWORD, _

BYVAL unit AS LONG _

) AS LONG

Parameters

metafile

[in] Pointer to the Metafile object.

unit

[in] Element of the Unit enumeration that specifies the unit of measure for this Graphics object.

GdipSetPixelOffsetMode

Description

Sets the pixel offset mode of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipSetPixelOffsetMode(

GpGraphics* graphics,

PixelOffsetMode pixelOffsetMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetPixelOffsetMode ( _

BYVAL graphics AS DWORD, _

BYVAL pixelOffsetMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

pixelOffsetMode

[in] Element of the PixelOffsetMode enumeration that specifies the pixel offset mode.

GdipSetRenderingOrigin

Description

Sets the rendering origin of this Graphics object. The rendering origin is used to set the dither origin for 8-bits-per-pixel and 16-bits-per-pixel dithering and is also used to set the origin for hatch brushes.

Syntax

GpStatus WINGDIPAPI GdipSetRenderingOrigin(

    GpGraphics *graphics,

    INT x,

    INT y

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetRenderingOrigin ( _

    BYVAL graphics AS DWORD, _

    BYVAL x AS LONG, _

    BYVAL y AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Integer that specifies the x-coordinate of the rendering origin.

[in] Integer that specifies the y-coordinate of the rendering origin.

GdipSetSmoothingMode

Description

Sets the render quality of the Graphics object.

Syntax

GpStatus WINGDIPAPI GdipSetSmoothingMode(

GpGraphics *graphics,

SmoothingMode smoothingMode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetSmoothingMode ( _

BYVAL graphics AS DWORD, _

BYVAL smoothingMode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

smoothingMode

[in] Element of the SmoothingMode enumeration that specifies whether smoothing (antialiasing) is applied to lines and curves.

Remarks

To get the rendering quality for text, use the GetTextRenderingHint function. The higher the level of quality of the smoothing mode, the slower the performance.

GdipSetTextContrast

Description

Sets the contrast value of this Graphics object. The contrast value is used for antialiasing text.

Syntax

GpStatus WINGDIPAPI GdipSetTextContrast(

GpGraphics *graphics,

UINT contrast

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetTextContrast ( _

BYVAL graphics AS DWORD, _

BYVAL contrast AS DWORD _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

contrast

[in] Unsigned integer value that specifies the contrast value for antialiasing text.

GdipSetTextRenderingHint

Description

Sets the text rendering mode of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipSetTextRenderingHint(

GpGraphics *graphics,

TextRenderingHint mode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetTextRenderingHint ( _

BYVAL graphics AS DWORD, _

BYVAL mode AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

mode

[in] Element of the TextRenderingHint enumeration that specifies the process currently used by this Graphics object to render text.

GdipSetWorldTrfansform

Description

Sets the world transformation of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipSetWorldTransform(

GpGraphics *graphics,

GpMatrix *matrix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetWorldTransform ( _

BYVAL graphics AS DWORD, _

BYVAL matrix AS DWORD _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

matrix

[in] Pointer to a Matrix object that specifies the world transformation.

GdipTransformPoints

Description

Converts an array of points from one coordinate space to another. The conversion is based on the current world and page transformations of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipTransformPoints(

    GpGraphics *graphics,

    GpCoordinateSpace destSpace,

    GpCoordinateSpace srcSpace,

    GpPointF *points,

    INT count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipTransformPoints ( _

    BYVAL graphics AS DWORD, _

    BYVAL destSpace AS LONG, _

    BYVAL srcSpace AS LONG, _

    BYREF pPoints AS PointF, _

    BYVAL count AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

destSpace

[in] Element of the CoordinateSpace enumeration that specifies the destination coordinate space.

srcSpace

[in] Element of the CoordinateSpace enumeration that specifies the source coordinate space.

points

[in, out] Pointer to an array that, on input, holds the points to be converted and, on output, holds the converted points.

count

[in] Long integer value that specifies the number of elements in the pts array.

Remarks

The world transformation converts points from the world coordinate space to the page coordinate space. The page transformation converts points from the page coordinate space to the device coordinate space.

GdipTransformPointsI

Description

Converts an array of points from one coordinate space to another. The conversion is based on the current world and page transformations of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipTransformPointsI(

    GpGraphics *graphics,

    GpCoordinateSpace destSpace,

    GpCoordinateSpace srcSpace,

    GpPoint *points,

    INT count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipTransformPointsI ( _

    BYVAL graphics AS DWORD, _

    BYVAL destSpace AS LONG, _

    BYVAL srcSpace AS LONG, _

    BYREF pPoints AS PointL, _

    BYVAL count AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

destSpace

[in] Element of the CoordinateSpace enumeration that specifies the destination coordinate space.

srcSpace

[in] Element of the CoordinateSpace enumeration that specifies the source coordinate space.

points

[in, out] Pointer to an array that, on input, holds the points to be converted and, on output, holds the converted points.

count

[in] Long integer value that specifies the number of elements in the pts array.

Remarks

The world transformation converts points from the world coordinate space to the page coordinate space. The page transformation converts points from the page coordinate space to the device coordinate space.

GdipTranslateClip

Description

Translates the clipping region of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipTranslateClip(

    GpGraphics *graphics,

    REAL dx,

    REAL dy

);

PowerBASIC Syntax

DECLARE FUNCTION GdipTranslateClip ( _

    BYVAL graphics AS DWORD, _

    BYVAL dx AS SINGLE, _

    BYVAL dy AS SINGLE _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Simple precision value that specifies the horizontal component of the translation.

[in] Simple precision value that specifies the vertical component of the translation.

GdipTranslateClipI

Description

Translates the clipping region of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipTranslateClipI(

    GpGraphics *graphics,

    INT dx,

    INT dy

);

PowerBASIC Syntax

DECLARE FUNCTION GdipTranslateClipI ( _

    BYVAL graphics AS DWORD, _

    BYVAL dx AS LONG, _

    BYVAL dy AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Long integer value that specifies the horizontal component of the translation.

[in] Long integer value that specifies the vertical component of the translation.

GdipTranslateWorldTransform

Description

Updates this Graphics object's world transformation matrix with the product of itself and a translation matrix.

Syntax

GpStatus WINGDIPAPI GdipTranslateWorldTransform(

    GpGraphics *graphics,

    REAL dx,

    REAL dy,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipTranslateWorldTransform ( _

    BYVAL graphics AS DWORD, _

    BYVAL dx AS SINGLE, _

    BYVAL dy AS SINGLE, _

    BYVAL order AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Simple precision value that specifies the horizontal component of the translation.

[in] Simple precision value that specifies the vertical component of the translation.

order

[in] Element of the MatrixOrder enumeration that specifies the order of multiplication. MatrixOrderPrepend specifies that the translation matrix is on the left, and MatrixOrderAppend specifies that the translation matrix is on the right. The default value is MatrixOrderPrepend.

Page last updated on Monday, 11 December 2006 11:11:40 +0100