L_RingEffectBitmap

#include "l_bitmap.h"

L_LTIMGSFX_API L_INT L_RingEffectBitmap (pBitmap, 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.

Returns

Comments

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 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 in the Document and Medical Imaging 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 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

Platforms

Windows 2000 / XP/Vista.

See Also

Example

This example loads a bitmap and applies a Spiral Effect over the loaded image.

 L_INT RingEffectBitmapExample(L_VOID)
{
   L_INT nRet;
   BITMAPHANDLE  LeadBitmap;   /* Bitmap handle to hold the loaded image. */
   L_UINT uXorg, uYorg, uRadius; 

   /* Load the bitmap, keeping the bits per pixel of the file */
   nRet = L_LoadBitmap (TEXT("%UserProfile%\\My Documents\\LEADTOOLS Images\\IMAGE1.CMP"), &LeadBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL); 
   if(nRet !=SUCCESS)
      return nRet;

   uXorg =  ( L_UINT)(LeadBitmap.Width/2); 
   uYorg =  (L_UINT)(LeadBitmap.Height/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. */
   nRet = L_RingEffectBitmap(&LeadBitmap, uXorg, uYorg, uRadius, 10, 0, RGB(0,0,0), 100, RING_COLOR | RING_FIXEDANGLE | RING_MAXRADIUS);
   if(nRet !=SUCCESS)
      return nRet;
   nRet = L_SaveBitmap(TEXT("%UserProfile%\\My Documents\\LEADTOOLS Images\\Result.BMP"), &LeadBitmap, FILE_BMP, 24, 0, NULL);
   if(nRet !=SUCCESS)
      return nRet;
   //free bitmap 
   if(LeadBitmap.Flags.Allocated)  
      L_FreeBitmap(&LeadBitmap);  
   return SUCCESS;
}