NAME                                                              (V36)
        CreateUpfrontHookLayer -- Create a new layer on top of existing layers,
                                  using supplied callback BackFill hook.

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

        struct layer *createupfronthooklayer(struct layer_info *, struct bitmap *,
            long, long, long, long, long, struct hook *, ... );

    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
        Install Layer->BackFill callback hook.
        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.
        hook -  Layer->BackFill callback hook (see installlayerhook())

                If hook is LAYERS_BACKFILL, the default backfill is
                used for the layer.  (Same as pre-2.0)

                As of V39:
                If hook is LAYERS_NOBACKFILL, the layer will not be
                backfilled (NO-OP).

        bm2 - pointer to optional Super bitmap

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

    BUGS

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