PhMakeTransBitmap()

Create a transparency mask for an image

Synopsis:

int PhMakeTransBitmap( PhImage_t *image,
                       PgColor_t trans_color );

Library:

ph

Description:

This function creates a transparent bitmap or transparency mask for the given image, provided there isn't one already.

---

PhMakeTransparent() is similar to PhMakeTransBitmap(), but PhMakeTransparent() uses chroma when possible; chroma is accelerated by most hardware, whereas transparency bitmaps are always implemented in software.

---

The meaning of the trans_color argument depends on the type of the image:

Pg_IMAGE_PALETTE_NIBBLE
Pg_IMAGE_PALETTE_BYTE

The trans_color argument is the color in the image's palette to be made transparent. If more than one entry in the palette contains this color, the first one found is used. You can pass an index into the palette as trans_color by ORing it with Pg_INDEX_COLOR. For example:

if ( PhMakeTransBitmap( my_image,
                        n | Pg_INDEX_COLOR ) == 0 )
{
    …
}

Pg_IMAGE_GRADIENT_BYTE
Pg_IMAGE_GRADIENT_NIBBLE

The trans_color argument is the grey index (0-255 for BYTE, 0-15 for NIBBLE) to be made transparent.

Pg_IMAGE_DIRECT_1555
Pg_IMAGE_DIRECT_4444
Pg_IMAGE_DIRECT_8888
Pg_IMAGE_DIRECT_888

The trans_color argument is the color to be made transparent, expressed as a PgColor_t.

Pg_IMAGE_DIRECT_565
Pg_IMAGE_DIRECT_444

The trans_color argument is interpreted as a short packed with the color information in the appropriate format (see PhImage_t).

The resulting bitmap is stored in the mask_bm member of the PhImage_t structure. This function sets the image's Ph_RELEASE_TRANSPARENCY_MASK flag.

To draw the image using the transparency mask, use PgDrawPhImage() or PgDrawPhImagemx().

Returns:

0

Success.

-1

An error occurred.

Examples:

/*
 * This is code for a PhAB application that demonstrates
 * how to make a transparency mask for an image.  This
 * also shows how to take that image and to put it into
 * a label widget and to draw it into a PtRaw's canvas.
 */

/* Standard headers */
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>

/* Toolkit headers */
#include <Ph.h>
#include <Pt.h>
#include <Ap.h>

/* Local headers */
#include "abimport.h"
#include "proto.h"

ApDBase_t   *database;
PhImage_t   trans_image;

/*
 * Setup function for the base window
 */
int
base_window_setup( PtWidget_t *link_instance,
                   ApInfo_t *apinfo,
                   PtCallbackInfo_t *cbinfo )
{
    PhImage_t   *imgptr;

    // Get the original image from an image-type
    // label widget that we've put in a PhAB picture
    // module - don't close the database since we'll
    // still be using its image and palette data

    database = ApOpenDBase( ABM_our_picture_module );
    imgptr = ApGetImageRes( database, "image_label" );

    // Copy it so that we don't change the original
    // PhImage_t; we'll still be using the same image
    // and palette data though

    memcpy( &trans_image, imgptr, sizeof(PhImage_t) );

    // all white pixels will be transparent

    PhMakeTransBitmap( &trans_image, Pg_WHITE );

    // Put the image that contains the transparency mask
    // into another image-type label

    PtSetResource( ABW_destination_label,
       Pt_ARG_LABEL_IMAGE, &trans_image, 0 );

    /* eliminate 'unreferenced' warnings */
    link_instance = link_instance, apinfo = apinfo;
    cbinfo = cbinfo;

    return( Pt_CONTINUE );
}

/*
 * Draw function (Pt_ARG_RAW_DRAW_F) for a PtRaw widget
 */
void
raw_draw_f( PtWidget_t *widget, PhTile_t *damage )
{
    PhPoint_t   pos = {0, 0};
    PhRect_t    rect;

    damage = damage;

    PtSuperClassDraw( PtBasic, widget, damage );

    // Find our canvas
    PtCalcCanvas( widget, &rect );

    // Set translation so that drawing is relative to
    // the PtRaw widget, not its parent.
    PgSetTranslation( &rect.ul, Pg_RELATIVE );

    // Clip to our basic canvas (it's only polite).
    PtClipAdd( widget, &rect );

    // Do our drawing...
    PgDrawPhImagemx( &pos, &trans_image, 0 );

    // Remove our translation and clipping
    rect.ul.x *= -1; // subtract what we added above
    rect.ul.y *= -1;
    PgSetTranslation( &rect.ul, Pg_RELATIVE );
    PtClipRemove();
}

Classification:

Photon

See also:

PgColor_t, PgDrawPhImage*(), PgDrawPhImageRect*(), PgDrawRepPhImage*(), PhCreateImage(), PhImage_t, PhMakeTransparent()

“Images” in the Raw Drawing and Animation chapter of the Photon Programmer's Guide