In This Topic ▼

L_SetBitmapAlpha

Summary

Replaces existing alpha channel data or creates new alpha channel data in the destination bitmap.

Syntax

#include "l_bitmap.h"

L_LTKRN_API L_INT L_SetBitmapAlpha(pBitmap, pAlpha)

Parameters

pBITMAPHANDLE pBitmap

Points to the destination bitmap handle, which references the bitmap where the alpha channel data will be updated or added.

pBITMAPHANDLE pAlpha

Points to the source bitmap handle, which references the bitmap that is used to create or replace the alpha channel data.

Returns

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

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.

Typically, an alpha channel contains a mask that is used for transparency. This function, together with L_GetBitmapAlpha and the LEADTOOLS region processing functions, lets you use the alpha channel to implement transparency.

Only 16-, 32- and 64-bit images can have an alpha channel. If pBitmap references a bitmap of any other color resolution, this function converts the pBitmap bitmap to 32-bit before it replaces the alpha channel. (If you want 16-bit, you should change it using L_ColorResBitmap, if necessary, before calling this function.)

For 64-bit bitmaps, pAlpha is converted to 16 bit grayscale before replacing the alpha channel. If pBitmap is 48-bit, it will be converted to 64-bit and then have the alpha information added to it.

The pAlpha bitmap does not have to be grayscale. This function converts the data from the pAlpha bitmap to the necessary grayscale or 1-bit format as it replaces the alpha channel in pBitmap. (The pAlpha bitmap, itself, remains unchanged.)

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, Linux.

Example

This example shows how to create, save, and use a mask for transparency.
We assume that the window has already been created and sized to fit the aspect
ratio of the image specified in pszFilename.

L_INT SetBitmapAlphaExample(HWND hWnd,L_TCHAR*  szFilename) 
{ 
   L_INT nRet; 
   BITMAPHANDLE   MainBitmap;           /* Main bitmap */ 
   BITMAPHANDLE   AlphaBitmap;          /* Alpha channel bitmap */ 
   RGNXFORM       XFormToBitmap;        /* Structure for transforming display coordinates */ 
   HDC            hWindowDC;            /* Device context of the current window */ 
   RECT           rClientArea;          /* Client area of the current window */ 
   RECT           rRgnRect;             /* Rectangle that defines the current region */ 
   HPALETTE       hSavedPalette = NULL; /* Temporary copy of the current system palette */ 
   HPALETTE       hOurPalette = NULL;   /* The palette that we will use to paint */ 
 
   /* Get the device context of the current window */ 
   hWindowDC = GetDC (hWnd);  
   /* Get the client area of the current window */ 
   GetClientRect(hWnd,&rClientArea); 
 
   /* Load a bitmap at 16 bits per pixel */ 
   nRet = L_LoadBitmap(szFilename, &MainBitmap, sizeof(BITMAPHANDLE), 16, ORDER_BGR, NULL, NULL); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   /* Set XFormToBitmap fields, assuming that the display rectangle is the same 
   as the client area of the current window */ 
   XFormToBitmap.uViewPerspective = TOP_LEFT; 
   XFormToBitmap.nXScalarNum      = BITMAPWIDTH(&MainBitmap); 
   XFormToBitmap.nXScalarDen      = rClientArea.right; 
   XFormToBitmap.nYScalarNum      = BITMAPHEIGHT(&MainBitmap); 
   XFormToBitmap.nYScalarDen      = rClientArea.bottom; 
   XFormToBitmap.nXOffset         = 0; 
   XFormToBitmap.nYOffset         = 0; 
 
   /* Specify a rectangle to define the region */ 
   SetRect(&rRgnRect, rClientArea.right/8, rClientArea.bottom/8,  
      rClientArea.right/2, rClientArea.bottom/2); 
 
   /* Create an elliptical region in the AlphaBitmap */ 
   nRet = L_SetBitmapRgnEllipse(&MainBitmap, &XFormToBitmap, &rRgnRect, L_RGN_SET); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   /* Create a mask bitmap from the region */ 
   nRet = L_CreateMaskFromBitmapRgn ( &MainBitmap, &AlphaBitmap, sizeof(BITMAPHANDLE)  ); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   /* Update the alpha channel in the main bitmap */ 
   nRet = L_SetBitmapAlpha(&MainBitmap, &AlphaBitmap); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   /* Save the bitmap at 16 bits per pixel to keep the alpha channel */ 
   nRet = L_SaveBitmap(MAKE_IMAGE_PATH(TEXT("Result.TIF")), &MainBitmap, FILE_TIF, 16, 0, NULL); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   /* Free the bitmaps */ 
   L_FreeBitmap(&MainBitmap); 
   L_FreeBitmap(&AlphaBitmap); 
 
   /* Load the bitmap that we just saved and get its alpha channel */ 
   nRet = L_LoadBitmap(MAKE_IMAGE_PATH(TEXT("Result.TIF")), &MainBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL); 
   if(nRet != SUCCESS) 
      return nRet; 
   nRet = L_GetBitmapAlpha(&MainBitmap, &AlphaBitmap, sizeof(BITMAPHANDLE)); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   /* Use the AlphaBitmap as a mask to set the region in the MainBitmap */ 
   nRet = L_SetBitmapRgnFromMask ( &MainBitmap, NULL, &AlphaBitmap, L_RGN_SET ); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   /* Create the palette that we will use to paint */ 
   hOurPalette = L_CreatePaintPalette(hWindowDC, &MainBitmap); 
   /* Select our palette and save the old one */ 
   hSavedPalette = SelectPalette (hWindowDC, hOurPalette, FALSE); 
   /* Realize our palette */ 
   RealizePalette (hWindowDC); 
   /* Paint the region */ 
   nRet = L_PaintRgnDC(hWindowDC,    /* Device context */ 
               &MainBitmap,   /* Bitmap handle */ 
               NULL,          /* Default source rectangle */ 
               NULL,          /* Default source clip area */ 
               &rClientArea,  /* Destination rectangle */ 
               NULL,          /* Default destination clipping rectangle */ 
               SRCCOPY);      /* ROP3 code for a Normal Paint */ 
   if(nRet != SUCCESS) 
      return nRet; 
 
   /* Restore the old palette */ 
   SelectPalette (hWindowDC, hSavedPalette, FALSE); 
   if(hOurPalette) 
      DeleteObject(hOurPalette); 
   /* Release the device context */ 
   ReleaseDC(hWnd, hWindowDC); 
   /* Free the AlphaBitmap */ 
   L_FreeBitmap(&AlphaBitmap); 
   L_FreeBitmap(&MainBitmap); 
   return SUCCESS; 
}