[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

	AllocScreenBuffer -- Get a ScreenBuffer for double-buffering. (V39)

	sbuffer = AllocScreenBuffer( Screen, BitMap, flags )
	D0                           A0      A1      D0

	struct ScreenBuffer *AllocScreenBuffer( struct Screen *,
	    struct BitMap *, ULONG );

	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.

	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.

	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!


	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.


	FreeScreenBuffer(), ChangeScreenBuffer(),
	graphics.library/AllocDBufInfo(), graphics.library/ChangeVPBitMap()

[Back to Amiga Developer Docs]