NAME
        CreateUpfrontLayer -- Create a new layer on top of existing layers.

    SYNOPSIS
        result = CreateUpfrontLayer(li,bm,x0,y0,x1,y1,flags [,bm2])
        d0                          a0 a1 d0 d1 d2 d3   d4  [ a2 ]

        struct layer *createupfrontlayer(struct layer_info *, struct bitmap *,
            long, long, long, long, long, ... );

    FUNCTION
        Create a new layer of position and size (x0,y0)->(x1,y1)
        and place it on top of all other layers.
        Make this layer of type found in flags
        if SuperBitMap, use bm2 as pointer to real SuperBitMap.
        and copy contents of Superbitmap into display layer.

        Note: when using SUPERBITMAP, you should also set LAYERSMART flag.

    INPUTS
        li - pointer to LayerInfo structure
        bm - pointer to common bitmap used by all layers
        x0,y0 - upper left hand corner of layer
        x1,y1 - lower right hand corner of layer
        flags - various types of layers supported as bit sets.
        bm2 - pointer to optional Super bitmap

    RESULTS
        result - pointer to layer structure if successful
                 NULL if not successful

    BUGS

    SEE ALSO
       deletelayer(), graphics/layers.h, graphics/clip.h, graphics/gfx.h