In This Topic ▼

LBitmap::RingEffect

#include "ltwrappr.h"

virtual L_INT LBitmap::RingEffect (nXOrigin, nYOrigin, uRadius, uRingCount, uRandomize, crColor, nAngle, uFlags)

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.

Parameters

L_INT nXOrigin

The X-Coordinate (in pixels) for the origin of the rings.

L_INT nYOrigin

The Y-Coordinate (in pixels) for the origin of the rings.

L_UINT 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.

L_UINT uRingCount

Number of rings.

L_UINT 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.

COLORREF crColor

The color used to fill the undefined area. This parameter is used only if uFlags contains RING_COLOR.

L_INT 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.

L_UINT uFlags

Flags which control the functions 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

Value	Meaning
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 LBase::EnableStatusCallback.

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.

This function does not support 32-bit grayscale images. It returns the error code ERROR_GRAY32_UNSUPPORTED if a 32-bit grayscale image is passed to this function.

Required DLLs and Libraries

LTIMGSFX
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

Win32, x64.

Example

L_INT LBitmap__RingEffectExample(LBitmap *pLeadBitmap)  
{ 
 
   /* This example applies a  Spiral Effect over the loaded image. */ 
   L_UINT uXorg, uYorg, uRadius;  
 
   uXorg =  (L_UINT)(pLeadBitmap->GetWidth ()/2);  
   uYorg =  (L_UINT)(pLeadBitmap->GetHeight ()/2);  
   uRadius = uXorg;  
 
   /* Apply a ring effect to this bitmap with origin (uXorg, uYorg). The maximum ring radius is equal to half of the bitmap's width. Draw 10 rings, fill the undefined areas with the Black color and the shift angle is equal to 1 degrees. Note that you will have undefined areas only if the bitmap width is greater than the bitmap height. */ 
   return pLeadBitmap->RingEffect( uXorg, uYorg, uRadius, 10, 0, RGB(0,0,0), 100, RING_COLOR | RING_FIXEDANGLE | RING_MAXRADIUS);  
}