IG_FX_spotlight

This function produces a "spotlight" effect within the circle specified by nRadius and (nCenterX, nCenterY).

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_FX_spotlight ( HIGEAR hIGear, const LPAT_RECT lpRect, const AT_PIXPOS nCenterX, const AT_PIXPOS nCenterY, const AT_DIMENSION nRadius, const UINT nDarkenBy, const AT_PIXEL nSmoothing );

Copy Code

AT_ERRCOUNT ACCUAPI IG_FX_spotlight (
        HIGEAR hIGear, 
        const LPAT_RECT lpRect, 
        const AT_PIXPOS nCenterX, 
        const AT_PIXPOS nCenterY, 
        const AT_DIMENSION nRadius, 
        const UINT nDarkenBy, 
        const AT_PIXEL nSmoothing
);

Arguments:

Name	Type	Description
hIGear	HIGEAR	HIGEAR handle of an image into which to place the spotlight effect.
lpRect	const LPAT_RECT	Far pointer to an AT_RECT struct specifying a rectangular portion of the image to be processed. NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nCenterX	const AT_PIXPOS	X coordinate of the center of the circle to receive a spotlight effect; 0 to Width - 1.
nCenterY	const AT_PIXPOS	Y coordinate of the center of the circle; 0 to Height - 1.
nRadius	const AT_DIMENSION	Radius of the circle, in pixels; 2 to Height - 2.
nDarkenBy	const UINT	How much to darken the remainder of the image.
nSmoothing	const AT_PIXEL	0 to 255, specifying how much smoothing to apply at the edges; 0 = sharp edges, > 0 = smoother edges.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Supported Raster Image Formats:

All pixel formats supported by ImageGear for C and C++, except:
Indexed RGB with non-grayscale palette;
Images that have a Grayscale LUT attached to them.

Example:

	Copy Code
HIGEAR hIGear; /* HIGEAR handle of image / AT_PIXPOS nXc, nYc; / Coords of center of spotlight area / AT_DIMENSION nWid, nHi; / Will receive width and height of image / UINT nBpp; / Bits per pixel, not used / AT_DIMENSION nRadius; / Radius of spotlight / IG_image_dimensions_get ( hIGear, &nWid, &nHi, &nBpp ); / Get Wid,Hi / nXc = nWid / 2; nYc = nHi / 2; / Coords of center / / Diameter will be half of smallest dimension: / nRadius = (nWid < nHi) ? nWid / 4 : nHi / 4; / Darken outside the circle by 40, with some smoothing of transition: */ IG_FX_spotlight ( hIGear, NULL, nXc, nYc, nRadius, 40, 10 );

Copy Code

HIGEAR hIGear;  /* HIGEAR handle of image   */
AT_PIXPOS nXc, nYc;  /* Coords of center of spotlight area */
AT_DIMENSION nWid, nHi; /* Will receive width and height of image */
UINT nBpp;     /* Bits per pixel, not used */
AT_DIMENSION nRadius;  /* Radius of spotlight  */
IG_image_dimensions_get ( hIGear, &nWid, &nHi, &nBpp ); /* Get Wid,Hi */
nXc = nWid / 2;   nYc = nHi / 2;   /* Coords of center */
/* Diameter will be half of smallest dimension:   */
nRadius =  (nWid < nHi) ?  nWid / 4  :  nHi / 4;
/* Darken outside the circle by 40, with some smoothing of transition:  */
IG_FX_spotlight ( hIGear, NULL, nXc, nYc, nRadius, 40, 10 );

Remarks:

This function leaves the pixels within the circle unchanged while darkening the surrounding pixels by reducing their intensity. Use nDarkenBy to specify the reduction in intensity of the surrounding pixels.

Use nSmoothing to specify the amount of smoothing at the perimeter of the circle. nSmoothing = 0 will leave the sharpest edge.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular sub-region of an image. (See above.) However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.