🚀 go-pugleaf

Regions:  The Real Story, a Technical Note	Copyright 1988 Juri Munkki
			  (Well, sort of)	All rights reserved

1.  What We Thought We Knew
	The May 1987 "ABC's of C" and October 1987 "C Workshop" in MacTutor
	provide descriptions of the region data structure. Obviously the region
	structure is reserved by apple and subject to change without notice
	(it's undocumented), but sometimes it's just too slow to do things the
	way apple intended us to do them. For this reason (and debugging
	purposes) it is useful to be aware of the structure.

	Unfortunately the "ABC's of C" article is not complete and the "C
	Workshop" gives slightly false information.

2.  Conventions
	In this article the structure I call the region is in fact the data
	that comes after the length word and size rectangle. The first 10 bytes
	are documented and are thus of no interest to us.

	While I'm on the subject of documentation, I might mention that the
	note in IM I-183 about the speed of OffSetRgn is misleading. None of
	the information in a region is stored in offset format and OffSetRgn
	is a relatively slow operation when the region is very complex.

3.  What We Now Know
	A region can be thought of as a collection of block descriptions, but
	each block is related to those above it. The block description starts
	with the smallest line coordinate included in the block and ends with a
	$7FFF. The words in between the start and end describe the difference
	between the current block and the one above it.

	Let's examine a union of two rectangles: 10,10-100,100 and 80,80-200,200

	The first line would then contain 10, 10, 100, $7FFF.
	This means that the first block starts at y position 10 and the pixels
	between x 10 and 100 are included in the block. The block extends
	until the block below it starts. The following block describes the
	changes to be made in the previous block. The second block would then
	be: 80, 100, 200, $7FFF. This means that those pixels that were
	between 100 and 200 should be inverted starting from y position 80.

	The next block would then tell to remove pixels between x positions
	10 and 80 starting from y position 100. It should look like this: 100,
	10, 80, $7FFF. The last block of our region would then cancel the
	remaining pixels from the block: 200, 80, 200, $7FFF. Since it is the
	last block, an extra $7FFF is appended.

	The complete region structure would look like this:

	  Y			Pixels set
	  10  10 100  $7FFF	10-100
	  80 100 200  $7FFF	10-200
	 100  10  80  $7FFF	80-200
	 200  80 200  $7FFF	None
	$7FFF

		+----+
	Block 1	|    |		10-100
		|  ..+----+
	Block 2	|  : :	  |	10-200
		+--+.:	  |
	Block 3	   |	  |	80-200
		   +------+
	Block 4
		   Figure 1

	In hexadecimal:
	000A, 000A, 0064, 7FFF, 0050, 0064, 00C8, 7FFF,
	0064, 000A, 0050, 7FFF, 00C8, 0050, 00C8, 7FFF, 7FFF

I hope this helps somebody. I thought about sending it to MacTutor, but then
decided against it. MacTutor is welcome to publish it if they want...

I reserve the rights to myself, so please do not reproduce in part
or whole without my permission.

Juri Munkki
jmunkki@santra.hut.fi
jmunkki@fingate.bitnet