NAME
        AllocScreenBuffer -- Get a screenbuffer for double-buffering. (v39)

    SYNOPSIS
        sbuffer = AllocScreenBuffer( screen, bitmap, flags )
        D0                           A0      A1      D0

        struct screenbuffer *allocscreenbuffer( struct screen *,
            struct bitmap *, ulong );

    FUNCTION
        Allocates a screenbuffer structure and usually a bitmap.  this
        structure can be used for double (or multiple) buffering in
        Intuition screens.  You may use this call to obtain a screenbuffer
        structure for the screen's initial bitmap, or for other bitmaps
        you intend to swap in.

        AllocScreenBuffer() also allocates a graphics.library dbufinfo
        structure.  The screenbuffer structure this call returns contains
        a pointer to that dbufinfo structure, which is free for your use.
        See graphics.library/allocdbufinfo() for full details on using
        this structure to achieve notification of when it is safe to
        render into an old buffer and when it is right to switch again.

    INPUTS
        screen = pointer to the screen to double-buffer
        bitmap = for custombitmap screens, you may pre-allocate
                a bitmap matching the screen's bitmap's properties, and
                pass that in, to get a screenbuffer referring to that
                bitmap.  set this parameter to null if you'd prefer
                that Intuition allocate the alternate buffer.  This parameter
                must be NULL for non-CUSTOMBITMAP screens.
        Flags = Set a combination of these flags:
            For non-CUSTOMBITMAP screens, set SB_SCREEN_BITMAP in order to
                get a screenbuffer referring to the screen's actual bitmap.
                (For CUSTOMBITMAP screens, just set the bitmap parameter
                to the bitmap you passed to openscreen()).
            Set SB_COPY_BITMAP if you would like the screen's bitmap
                copied into this ScreenBuffer's bitmap.  this is required
                to get any menu-bar or gadget imagery into each
                ScreenBuffer's bitmap.  if the screen has no intuition
                rendering, you may omit this flag.  Also, when allocating
                a screenbuffer for the screen's initial bitmap, this flag
                should not be set.

    RESULT
        Pointer to a valid screenbuffer structure, or null if failure.
        You may render into the resulting bitmap as appropriate.
        You may use the sb_DBufInfo field to access graphics.library
        ViewPort-buffering features such as learning when it is safe
        to reuse the previous bitmap.  if not, you risk writing into
        the on-screen bitmap, which can damage menu or gadget rendering!

    NOTES

        The role of SB_SCREEN_BITMAP is to wrap a screenbuffer around
        the actual current bitmap used by the non-custombitmap screen.
        The words actual or current are used instead of initial, since
        an application could do some double-buffering, leave the
        non-initial buffer installed into the screen, free up the
        others, then re-allocate screenbuffer structures to do more
        double-buffering.  In that case, the actual screen bitmap is
        not necessarily the initial one.

        The role of SB_COPY_BITMAP is to say "please put whatever
        imagery is currently on-screen into this new bitmap too".
        That's how the screen titlebar and other imagery get copied
        over into each buffer.

    BUGS

    SEE ALSO
        freescreenbuffer(), changescreenbuffer(),
        graphics.library/allocdbufinfo(), graphics.library/changevpbitmap()