L_RingEffectBitmap

#include "l_bitmap.h"

L_INT EXT_FUNCTION L_RingEffectBitmap (pBitmap, nXOrigin, nYOrigin, uRadius, uRingCount, uRandomize, crColor, nAngle, uFlags);

pBITMAPHANDLE pBitmap;	/* pointer to the bitmap handle */
L_INT nXOrigin;	/* the X – coordinate of the rings’ center */
L_INT nYOrigin;	/* the Y – coordinate of the rings’ center */
L_UINT uRadius;	/* maximum radius of all the rings or the width of each ring */
L_UINT uRingCount;	/* number of rings */
L_UINT uRandomize;	/* starting point for randomization process */
COLORREF crColor;	/* color for filling exposed areas */
L_INT nAngle;	/* angle of rotation */
L_UINT uFlags;	/* flags */

Divides the image into the specified number of rings. Each ring is rotated according to a rotation angle. The rotation angle for each ring will be chosen randomly by the function or can be passed to the function. This function is available in the Raster Pro and above toolkits.

Parameter	Description
pBitmap	Pointer to the bitmap handle referencing the bitmap to be modified.
nXOrigin	The X-Coordinate (in pixels) for the origin of the rings.
nYOrigin	The Y-Coordinate (in pixels) for the origin of the rings.
uRadius	If the flag RING_RADIUS is set in uFlags, this is the width of each ring, in pixels. If RING_MAXRADIUS is set in uFlags, this is the maximum radius, in pixels. In this latter case, the width of each ring is equal to uRadius / uRingCount + 1.
uRingCount	Number of rings.
uRandomize	The starting point for randomization process. Valid range is 0-500. If 0, the function will pick the starting point. If > 0, this value will be the starting point.
crColor	The color used to fill the undefined area. This parameter is used only if uFlags contains RING_COLOR.
nAngle	The rotation angle value for each ring compared to the inner ring, in hundredths of degrees. This parameter is used only if uFlags contains RING_FIXEDANGLE. The range of the acceptable values is from –18000 to 18000. This value is divided internally by 100.
uFlags	Flags which control the function’s behavior. These flags can be OR-ed together with any other flag, unless otherwise specified.
	Value	Meaning
	RING_COLOR	[0x0000] Controls the output of rings which have undefined areas. Fill the undefined areas with color crColor. If you use this flag, do not use RING_REPEAT or RING_NOCHANGE.
	RING_REPEAT	[0x0001] Controls the output of rings which have undefined areas. Repeat the edges of the region and fill these values in the undefined areas. The edge will be repeated halfway throughout the missing portion of the ring. If you use this flag, do not use RING_COLOR or RING_NOCHANGE.
	RING_NOCHANGE	[0x0002] Controls the output of rings which have undefined areas. Leave the edge pixels unchanged. If you rotate an incomplete ring, the original bitmap pixels will remain in places where you would have undefined portions of the ring. If you use this flag, do not use RING_COLOR or RING_REPEAT.
	RING_FIXEDANGLE	[0x0010] Rotate each ring against the inner ring by a fixed rotation angle (nAngle).
	RING_RADIUS	[0x0100] Indicates that uRadius contains the width of each ring, in pixels. If you use this flag, do not use RING_MAXRADIUS.
	RING_MAXRADIUS	[0x0200] Indicates that uRadius contains the maximum radius, in pixels, that corresponds to the external ring. In this case, the width of each ring is uRadius / uRingCount + 1. If you use this flag, do not use RING_RADIUS.

Returns

SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

This function can process the whole image or a region of the image. If a bitmap has a region, the effect is applied only to the region.

Divides the image into a certain number of rings. Each ring is rotated compared to its inner ring according to a shift angle. The function will pick the shift angle at random (if RING_FIXEDANGLE flag is not set) or will use the angle specified by nAngle (RING_FIXEDANGLE flag is set).

If RING_FIXEDANGLE flag is not set then the function will pick the shift angle randomly. The starting point (that is, the "randomize value") for the random number generator is selected through the uRandomize parameter, as follows:

If uRandomize is set to zero then the function will select a random value between 1 and 500 for the randomize value.

If uRandomize is > 0, it will be used for the randomize value. Note that uRandomize should be between 1 and 500 in this case.

Although the numbers generated are random, if you start with the same randomize value you will always get the same sequence of random numbers. This means that if you call the function twice with the same value for uRandomize, you will get the same result.

The center of the rings is determined by the nXOrigin and nYOrigin parameters. The function calculates the width of each ring by dividing the maximum radius (uRadius when uFlags is set to RING_MAXRADIUS) by the number of rings (uRingCount + 1).

The minimum width of each circle is 2. If the result of the division is less than 2, the function will draw uRadius / 2 rings, each ring having a width of 2.

Rings with a large radius might not be completely inside the bitmap. We will refer to these as "incomplete rings". We will refer to a portion of the ring that is outside the bitmap as "undetermined portion". When you rotate an incomplete ring, an undetermined portion of the ring might come into view. The function has 3 ways of specifying the output of the pixels where undetermined portions come into view:

Leave original bitmap pixels unchanged (RING_NOCHANGE is set) or

Repeat edge pixels (RING_REPEAT is set) or

Fill the undefined area with color crColor (RING_COLOR is set).

The determined portion of the ring will always displace the original bitmap pixels.

The image is split into an innermost circle and a number of rings. The innermost circle will not be rotated. Each ring is rotated compared to the inner ring. The rotation angle is as follows:

If RING_FIXEDANGLE is set, each ring will be rotated against its inner ring by nAngle. In other words, each index will be rotated against the original position by nAngle * <ring index>. (The index is 0-based. The innermost circle is considered to have an index of 0 and will not be rotated).

If RING_FIXEDANGLE is not set, the function will pick random rotation angles for each ring.

The width of the ring is determined as follows:

If RING_RADIUS is set, uRadius is the width of each ring

If RING_MAXRADIUS is set, uRadius will be the maximum ring radius. In this case, the width of each ring will be uRadius / uRingCount + 1.

This function supports all bits/pixel supported by LEADTOOLS.

But support for 12 and 16-bit grayscale and 48 and 64-bit color images is available only in the Document/Medical toolkits.

To update a status bar or detect a user interrupt during execution of this function, refer to L_SetStatusCallback.

This function does not support signed data images. It returns the error code ERROR_SIGNED_DATA_NOT_SUPPORTED if a signed data image is passed to this function.

Required DLLs and Libraries

LTIMG

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Windows 95 / 98 / Me, Windows 2000 / XP.

Functions:	L_MosaicBitmap, L_PicturizeBitmap, L_PicturizeBitmapList, L_PicturizeBitmapSingle, L_PixelateBitmap, L_CubismBitmap, L_DiceEffectBitmap, L_PuzzleEffectBitmap, L_BricksTextureBitmap, L_CanvasBitmap, L_CloudsBitmap, L_ColoredBallsBitmap, L_DiffuseGlowBitmap, L_DisplaceMapBitmap, L_FragmentBitmap, L_HalfTonePatternBitmap, L_MaskConvolutionBitmap, L_MosaicTilesBitmap, L_OffsetBitmap, L_PerspectiveBitmap, L_PlasmaFilterBitmap, L_PointillistBitmap, L_RomanMosaicBitmap, L_VignetteBitmap, L_ZigZagBitmap
Topics:	Raster Image Functions: Artistic Effects
	Applying Artistic Effects
	Using Color Values in LEADTOOLS