[Alephmodular-devel] Brainstorming on CBuffers

[Br'fin <br...@ma...>]

Trying to hash out Buffers. This is better. Though I feel the hierarchy 
may be off or the clipping buffers might be off. Hrm.

-Jeremy Parsons

Buffers

A buffer is a complete description of a surface that one can draw upon. 
It is an abstract base class with platform specific implementations. 
For instance, under Macintosh, a buffer would wrap around a 
GWorldPtr/CGraftPtr/GrafPtr.

Typical usage would be:
	Request current buffer from display system
		(it is limited as in dimensions, display system knows this)
	Lock down the buffer
	Get a bitmap from the buffer
	Render operations on the bitmap
	Release the bitmap
	Perform drawing operations on the buffer (access to platform native 
elements available?)
	Unlock the buffer
	Ask display system to swap buffers
	
A buffer helps support higher level options such as copying portions 
and displaying text using OS specific calls.

world_pixels would be a buffer.

Buffer attributes
	Height/Width
	Bit Depth
	Clut (8 bit depth only?)

Here is a set of methods for buffers suggested by how existing Marathon 
code uses world_pixels:

Locking pixels. (std::auto_ptr<CBuffer::PixelLock> get_pixel_lock) When 
dealing with buffers on Macintosh, one must lock down pixels before 
doing certain operations. Such as rendering onto the bitmap or using 
copybits. With an auto_ptr based mechanism, the lock is automatically 
freed once out of scope. A corrolary of this is that directly 
requesting a buffer's bitmap should make sure the corresponding bitmap 
has locked the buffer and has control of the lock. Trying to double 
lock or doubly unlock a buffer should assert.

Instantiating and updating the internal buffer. Both myUpdateGWorld and 
myNewGWorld are called, depending on whether or not world_pixels 
already exists. Updates included depth, bounds, clut and associated 
screen device and flags. This may be protected functionality handled by 
the display abstraction. Since we are adding funtionality to the buffer 
(like by being able to use pre-existing buffers as if we had allocated 
them, such as the natural back buffer of a window) these may not have 
direct correlations to the outside world anymore.

Accessing pixels. (std::auto_ptr<CBitmap> or facsimile) Gets a bitmap 
preconfigured by the buffer. Trying to access the pixels with another 
access on the pixels outstanding is a failure and should assert.

Clipping requests (std::auto_ptr<CBuffer::ClipLock> 
lock_clipping_region(left/top/right/bottom)) Specifies boundaries for 
drawing operations. For instance, during map drawing you may wish to 
draw wildly all over the place. But only the details that actually fall 
within the clipping area should be displayed. This is apt to be a 
protected operation performed for you by a clipping buffer.

Boundary requests: aka GetPortBounds

Buffers will either be allocated for you. (Ask the Display manager for 
the buffer to use!) or by knowingly using the platform specific buffer 
calls.

There will be cause to have clipped buffers. That is, a buffer that has 
its own height and width, but which is actually a window into a larger 
buffer. For instance, the raw display buffer could be your screen at 
1024x768 and the outermost buffer would need to point to this. But for 
game purposes, it only cares about a 640x480 space for the entire 
display area. And on top of that it typically only uses 640x320 for the 
game world, and the remaining space for the HUD. A clipped buffer 
performs two operations for you. It is automatically clipped. And its 
origin is shifted to the top/left of the clipping region.

CBuffer hierarchy

CBuffer
	Root Class
CPlatformBuffer : public CBuffer
	CBuffer class the is root for platform specific buffer classes. For
	instance, direct calls for clipping would be within this class's 
interface.
	CBuffer_Carbon would be a descendant of this.
CClippedBuffer : public CBuffer
	CBuffer class that does origin translation and clipping effects to act 
as a
	subset of its root buffer.
world_pixels usage:

game_window_macintosh.cpp
	used within draw_panels
		HUD is drawn in back buffer
		copy bits called to send it to the screen
preprocess_map_mac.cpp
	world_pixels is used as the offscreen buffer for saved game preview 
pictures :/
screen.cpp
	world_pixels is setup during initialize_screen
	world_pixels provides the pixels for use in render_screen
	world_pixels clut is updated to sync with screen in change_screen_clut
	world_pixels is used in render_computer_interface
	world_pixels is used in render_overhead_map
	world_pixels is copied from in update_screen
		(and used as source for quadruple_screen!)
screen_drawing.cpp
	_set_port_to_gworld encapsulates swapping to world_pixels for gWorld 
foo.