L_UpdateMagGlass

#include "l_bitmap.h"

L_LTDIS_API L_INT L_UpdateMagGlass(hWnd, pColor, pMaskPlane, nMaskPlaneStart, nMaskPlaneEnd, bUpdateBitmap)

L_HWND hWnd;	/* handle to a window */
L_COLORREF * pColor;	/* starting position of the mask plane array */
L_UCHAR* pMaskPlane;	/* end position of the mask plane array */
L_INT nMaskPlaneStart;	/* array of bit flags */
L_INT nMaskPlaneEnd;	/* color buffer */
L_BOOL bUpdateBitmap;	/* flag that indicates whether to update the bitmap */

Updates the zoomed image displayed in the Magnifying Glass display area.

Parameter	Description
hWnd	Handle of the window to which the Magnifying Glass is attached.
pColor	The starting position of the mask plane array.
pMaskPlane	The end position of the mask plane array.
nMaskPlaneStart	An array of bit flags which represents a mask plane. This array works as a plane for the parts of the bitmap that are not yet updated.
nMaskPlaneEnd	Value that represents the color buffer used to update parts of the bitmap as soon as the left button is pressed and the mouse moves on the window.
bUpdateBitmap	Flag that indicates whether to update the bitmap passed to L_StartMagGlass. Possible values are:
	Value	Meaning
	TRUE	Update the bitmap passed to L_StartMagGlass. (The updated areas will be seen while moving the magnifying glass over the image and the bitmap will be updated.)
	FALSE	Do not update the bitmap passed to L_StartMagGlass. (The updated areas will be seen while moving the magnifying glass over the image but the bitmap will not be updated.)

Returns

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

Comments

This function can only be called if a callback function was passed to L_StartMagGlass. If a callback function is passed to L_StartMagGlass, information about the non-updated parts of the bitmap can be obtained from the callback function. This information can then be used with LEADTOOLS Internet functions to get fill a pColor buffer with pixel values for the non-updated parts of the bitmap. Once this pColor buffer is filled and received, that information and the pColor buffer can be passed to this function to update the Magnifying Glass image.

For an example, refer to the Ltnetdlln.chm help file in the HELP directory.

The pColor buffer can also be filled without using the LEADTOOLS Internet functions. Match pMaskPlane, received in the callback function, to the original bitmap and fill pColor buffer with the corresponding pixel colors. The following example explains this procedure.

The figure below represents a bitmap 29 pixels wide and 20 pixels high. The pixels are represented by the small blue squares.

$image\UpdateMag.gif$

Define a MAGGLASSCALLBACK callback function and pass it to L_StartMagGlass to start the Magnifying Glass. When the left mouse button is pressed while moving the mouse over the bitmap, the MAGGLASSCALLBACK function will receive the (hWnd, nMaskPlaneStart, nMaskPlaneEnd, pMaskPlane, nMaskPlaneSize and pUserData) information. Each time the callback receives this information, it indicates that part of the bitmap needs to be updated. The bitmap can be updated by calling the L_UpdateMagGlass function.

The large black squares in the figure above represent portions of the bitmap. Each portion can contain a maximum of 64 pixels (8 by 8). Occasionally, portions may have less than 64 pixels, especially those portions at the edge of the bitmap. Each portion is represented by 1 bit of the bytes in the pMaskPlane array.

For example, if the Magnifying Glass is moved over the bitmap from pixel coordinate (9, 3), shown in red in the image above, to (28, 17), shown in green in the image above, then the following portions are affected: 1, 2, 3, 5, 6, 7, 9, 10 and 11.

Therefore, 9 portions are represented in the pMaskPlane. Each portion is represented by 1 bit within the pMaskPlane. Therefore, 2 bytes are needed in the pMaskPlane to represent the 9 portions of the bitmap. Each portion will be mapped to a byte in the pMaskPlane array as follows:

Portion Number	Bit Index	Byte Index
1	0	0
2	1	0
3	2	0
5	3	0
6	4	0
7	5	0
9	6	0
10	7	0
11	0	1

So, the pMaskPlane received from the MAGGLASSCALLBACK function will contain 2 bytes. Each bit of those 2 bytes will be filled with zero or one indicating whether or not the portion has been updated. The nMaskPlaneStart parameter of the callback will equal 1 and the nMaskPlaneEnd parameter will equal 11. nMaskPlaneSize will equal 2.

The next step is to check each bit value. If the bit value is 1 the corresponding portion needs to be updated, so pColor buffer must be filled with the corresponding pixel colors. Start with the portion indicated in nMaskPlaneStart. In this example that is portion number 1. If the bit representing portion 1 has a value of 1, then the pColor buffer should be filled with the corresponding pixels from the original bitmap. You must always start filling the pColor buffer array from the first pixel in the portion. For portion 1, the first pixel has coordinates (8, 0). Move through the row until the last pixel of that portion is reached. In this case, the last pixel in the first row of portion 1 has coordinates (15, 0). Next, move to the next row and add the pixel colors of this row to pColor buffer. Continue in this manner until the last pixel of the portion is reached. In this example the last pixel in portion 1 has the coordinates (15,7).

Having finished one portion, move to the next portion. In this example the next portion is portion 2. Check the bit value in pMaskPlane for this portion. Suppose it has a bit value of 0. For this portion, do not fill pColor buffer with the pixel colors of the original bitmap. Proceed through the remaining portions until the portion indicated by nMaskPlaneEnd is reached.

By following this procedure pColor buffer can be filled with the necessary pixel colors and passed, along with other information, to this function (L_UpdateMagGlass) and used to update the zoomed image displayed in the Magnifying Glass display area.

If bUpdateBitmap is TRUE, the original bitmap will be updated when the mouse moves over the bitmap while the left mouse button is pressed.

Required DLLs and Libraries

LTDIS

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 2000 / XP/Vista, Windows CE.

Functions:	L_StartMagGlass, L_StopMagGlass, MAGGLASSCALLBACK, L_CreateZoomView, L_GetZoomViewProps, L_UpdateZoomView, L_DestroyZoomView, L_GetZoomViewsCount, L_WindowHasZoomView, ZOOMVIEWPROPS
Topics:	Using the Magnifying Glass
	Raster Image Functions: Displaying Images
	Using the Zoom View