Re: [Alephmodular-devel] Brainstorming on bitmaps

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

And more brainstorming:

-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.

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.

Setting as target of drawing operations 
(std::auto_ptr<CBuffer::DrawbleLock> get_drawing_lock). Encapsulation 
for MacOS concepts of setting/swapping current drawing target with our 
buffer, then restoring the old drawing target afterwards. Attempts to 
perform drawing operations without this lock should assert. Attempts to 
get a second drawing lock should work though, in assumption of attempts 
to nest calls to drawing to different buffers.
Ponder... Setting the drawing context should occur seperately

Boundary requests: aka GetPortBounds

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.