L_GetOverlayBitmap

#include "l_bitmap.h"

L_LTKRN_API L_INT L_GetOverlayBitmap (pBitmap, nIndex, pOverlayBitmap, uStructSize, uFlags)

pBITMAPHANDLE pBitmap;	/* pointer to the main bitmap handle */
L_INT nIndex;	/* the overlay index */
pBITMAPHANDLE pOverlayBitmap;	/* pointer to the overlay bitmap handle */
L_UINT uStructSize;	/* the size of the BITMAPHANDLE structure */
L_UINT uFlags;	/* flags that determine setting options */

Gets the overlay bitmap for the specified index.

Parameter	Description
pBitmap	Pointer to the bitmap handle referencing the main bitmap.
nIndex	The index of the overlay being retrieved. This index is zero-based.
pOverlayBitmap	Pointer to the overlay bitmap handle to be updated with the overlay bitmap at the specified index. This cannot be NULL.
uStructSize	Size of the BITMAPHANDLE structure pointed to by pOverlayBitmap. Pass sizeof(BITMAPHANDLE).
uFlags	Flags that determine how to retrieve the bitmap. You cannot combine these flags. Possible values are:
	Value	Meaning
	OVERLAY_COPY	[0x0000] A copy of the overlay bitmap is retrieved from the overlay list.
	OVERLAY_NOCOPY	[0x0001] The actual overlay bitmap is retrieved. No copy is made. You should be careful when modifying the overlay bitmap because you can modify/invalidate the entry in the overlay bitmap list.
	OVERLAY_MOVE	[0x0003] The actual overlay bitmap is retrieved. The bitmap is also removed from the overlay list. This is recommended over OVERLAY_NOCOPY.

Returns

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

Comments

This function can be used to get a copy of the overlay bitmap (OVERLAY_COPY) or to get the bitmap without making a copy (OVERLAY_NOCOPY or OVERLAY_MOVE).

The quickest way to get the overlay bitmap is to avoid making a copy. For more information on using OVERLAY_NOCOPY, refer to the "Comments" section of L_SetOverlayBitmap.

If OVERLAY_MOVE is set in uFlags, the overlay bitmap from the corresponding index will be invalidated.

pOverlayBitmap is assumed to be unallocated and uninitialized. It will be filled without freeing the existing data.

Required DLLs and Libraries

LTKRN

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.

See Also

Functions:	L_SizeBitmap, L_StartResize, L_Resize, L_StopResize, L_SetOverlayBitmap, L_SetOverlayAttributes, L_GetOverlayAttributes, L_UpdateBitmapOverlayBits, L_GetOverlayCount, L_BricksTextureBitmap, L_CanvasBitmap, L_DisplaceMapBitmap, L_FragmentBitmap, L_VignetteBitmap
Topics:	Raster Image Functions: Combining Images
	Overlay Overview

Example

This example will get the overlay bitmaps and save them to separate files.

 L_INT GetOverlayBitmapExample(HWND hWnd, pBITMAPHANDLE pBitmap)
{
   L_INT          nRet;
   BITMAPHANDLE   OverlayBitmap;
   L_INT          i;
   L_TCHAR        s[MAX_PATH];

   for(i = 0; i < MAX_OVERLAYS; i++)
   {
      // note that I am using OVERLAY_NOCOPY, so I should not free the overlay bitmap!
      nRet = L_GetOverlayBitmap(pBitmap, i, &OverlayBitmap, sizeof(BITMAPHANDLE), OVERLAY_NOCOPY);
      if(nRet == SUCCESS)
      {
         wsprintf(s, MAKE_IMAGE_PATH(TEXT("overlay%d_copy.cmp")), i);
         nRet = L_SaveBitmap(s, &OverlayBitmap, FILE_LEAD1BIT, 1, 1, NULL);
         if(nRet != SUCCESS)
         {
            MessageBox(hWnd, TEXT("Error saving file!"), s, MB_OK);
            return nRet;
         }
      }
      else
      {
         return nRet;
      }
   }
   return SUCCESS;
}