Implementing Transparency

You can implement transparency when doing any of the following:

• Animation. When playing an animation, the playback process recognizes the transparent color and the transparency flag specified in the BITMAPHANDLE of each bitmap. The transparent color is loaded from and saved to GIF files. If you save animated files in other multipage formats, you must maintain this BITMAPHANDLE information yourself. For more information, refer to Implementing Animation.

• Paint effects. When painting a bitmap or other object, you can specify a transparent color. Keep in mind that you must use one of the special effects functions, such as L_EfxPaintBitmap, and you must pass the color in a parameter. (For example, you could pass the transparent color that is specified in the BITMAPHANDLE of a GIF image.) For more information about paint effects, refer to Implementing Special Effects.

• Region processing. Defining a region in a bitmap makes it possible to treat the area outside the region as transparent. The L_PaintRgnDC function paints only the region that is defined for a bitmap. The L_CombineBitmap function combines only the area inside the region. You can define a region in a number of ways, including specification of a color. For example, if a transparent color is defined for a bitmap, you can create a region that omits pixels of that color. For details, refer to Creating a Bitmap Region.

Once a region is defined, you can create a mask from it, using the L_CreateMaskFromBitmapRgn function, which you can save in the alpha channel of a 16- or 32-bit file. Refer to the L_SetBitmapAlpha function for an example of how to save a region in an alpha channel.

When specifying a transparent color, you can use the Windows PALETTEINDEX macro to refer to a particular palette index (where the COLORREF value is >= 0x01000000). Using a palette index for transparency means that one of the remaining colors in the palette can have the same RGB value as the transparent color, without being interpreted as transparent.

L_FeatherAlphaBlendBitmap is a powerful function that can be used to implement transparency, using a mask. In many applications, a transparency mask is saved as an alpha channel. If a bitmap contains a transparency mask in the alpha channel, call L_GetBitmapAlpha to get the alpha channel information back into a bitmap form. Once the transparency mask information is in a bitmap, it can be passed directly to the L_FeatherAlphaBlendBitmap function as the mask. The following code demonstrates how to do this:

void TestFunction(HWND hWnd, pBITMAPHANDLE pDstBitmap) 
{ 
   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 */ 
   L_INT nRet; 
   /* 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("TEST.bmp", &MainBitmap, sizeof(BITMAPHANDLE), 16, ORDER_BGR, NULL, NULL); 
   /* 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); 
   /* Create a mask bitmap from the region */ 
   nRet = L_CreateMaskFromBitmapRgn ( &MainBitmap, &AlphaBitmap, sizeof(BITMAPHANDLE)  ); 
   /* Update the alpha channel in the main bitmap */ 
   nRet = L_SetBitmapAlpha(&MainBitmap, &AlphaBitmap); 
   /* Save the bitmap at 16 bits per pixel to keep the alpha channel */ 
   nRet = L_SaveBitmap("TEST.TIF", &MainBitmap, FILE_TIF, 16, 0, NULL); 
    
   /* Free the bitmaps */ 
   L_FreeBitmap(&MainBitmap); 
   L_FreeBitmap(&AlphaBitmap); 
   /* Load the bitmap that we just saved and get its alpha channel */ 
   nRet = L_LoadBitmap("TEST.TIF", &MainBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL); 
   nRet = L_GetBitmapAlpha(&MainBitmap, &AlphaBitmap, sizeof(BITMAPHANDLE)); 
    
   nRet = L_FeatherAlphaBlendBitmap(pDstBitmap, 0, 0, AlphaBitmap.Width, AlphaBitmap.Height, &MainBitmap, 0, 0, &AlphaBitmap, 0, 0, 0); 
   L_FreeBitmap(&MainBitmap); 
   L_FreeBitmap(&AlphaBitmap); 
   return; 
} 

Setting Transparent Colors For Annotation Bitmap Objects (Document and Medical Imaging toolkits)

The annotation Stamp object (ANNOBJECT_STAMP, which includes the different Rubber Stamp tools) and Point object (ANNOBJECT_POINT) can be set to display bitmaps that use a transparent color. A transparent color is a color that is not painted when the image is painted. Call the L_AnnSetTransparent function to set such objects to use a transparent color. By default the transparent color is white (0x00FFFFFF). Use the L_AnnSetTransparentColor function to set the color to be used as the transparent color. Use the L_AnnGetTransparent function to get a value that indicates whether the bitmap being used by the annotation object is using a transparent color. Use the L_AnnGetTransparentColor function to get a value that indicates which color is being used as the transparent color.