Blitter Objects - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:05:11Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:05, 26 January 2025
Line 36:		Line 36:
	To have the GEL routines save the background before the Bob is drawn and restore the background after the Bob is removed, specify the SAVEBACK flag (stands for "save the background") in the VSprite structure Flags field. If this flag is set, the SaveBuffer must have been allocated, which is where the system puts this saved background area. The buffer must be large enough to save all the background bitplanes, regardless of how many planes the Bob has. The size in words can be calculated as follows:		To have the GEL routines save the background before the Bob is drawn and restore the background after the Bob is removed, specify the SAVEBACK flag (stands for "save the background") in the VSprite structure Flags field. If this flag is set, the SaveBuffer must have been allocated, which is where the system puts this saved background area. The buffer must be large enough to save all the background bitplanes, regardless of how many planes the Bob has. The size in words can be calculated as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/* Note that Bob.Width is in units of words. */		/* Note that Bob.Width is in units of words. */
	size = Bob.Width * Bob.Height * RastPort.BitMap.Depth;		size = Bob.Width * Bob.Height * RastPort.BitMap.Depth;
Line 43:		Line 43:
	To allocate this space, the graphics function AllocRaster() can be used. AllocRaster() takes the width in bits, so it is a convenient way to allocate the space needed. The makeBob() routine below shows another way to correctly allocate this buffer. For example:		To allocate this space, the graphics function AllocRaster() can be used. AllocRaster() takes the width in bits, so it is a convenient way to allocate the space needed. The makeBob() routine below shows another way to correctly allocate this buffer. For example:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/* space for 16 bits times 5 lines times 5 bitplanes */		/* space for 16 bits times 5 lines times 5 bitplanes */
	myBob.SaveBuffer = AllocRaster( 16, (5 * 5) );		myBob.SaveBuffer = AllocRaster( 16, (5 * 5) );
Line 58:		Line 58:
	The Bob structure is defined in the include file <graphics/gels.h> as follows:		The Bob structure is defined in the include file <graphics/gels.h> as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Bob		struct Bob
	{		{
Line 75:		Line 75:
	The Bob structure itself does not need to be in Chip memory. The (global) static declaration of a Bob structure could be done like so:		The Bob structure itself does not need to be in Chip memory. The (global) static declaration of a Bob structure could be done like so:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Bob myBob =		struct Bob myBob =
	{		{
Line 88:		Line 88:
	The VSprite and Bob structures must point to one another, so that the system can find the entire GEL. The structures are linked with statements like this:		The VSprite and Bob structures must point to one another, so that the system can find the entire GEL. The structures are linked with statements like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	myBob.BobVSprite = &myVSprite;		myBob.BobVSprite = &myVSprite;
	myVSprite.VSBob = &myBob;		myVSprite.VSBob = &myBob;
Line 121:		Line 121:
	As an example, suppose the Bob is 24 pixels wide and 20 lines tall. Use statements like the following to specify the size:		As an example, suppose the Bob is 24 pixels wide and 20 lines tall. Use statements like the following to specify the size:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	myVSprite.Height = 20; /* 20 lines tall. */		myVSprite.Height = 20; /* 20 lines tall. */
	myVSprite.Width = 2; /* 24 bits fit into two words. */		myVSprite.Width = 2; /* 24 bits fit into two words. */
Line 166:		Line 166:
	For example, if a Depth of one plane is specified, then the bits of that image allow only two colors to be selected: one color for each bit that is a 0, a second color for each bit that is a 1. Likewise, if there are 5 planes of image data, all 32 colors can be used in the Bob. The Bob Depth must not exceed the background depth. Specify Depth using a statement such as the following:		For example, if a Depth of one plane is specified, then the bits of that image allow only two colors to be selected: one color for each bit that is a 0, a second color for each bit that is a 1. Likewise, if there are 5 planes of image data, all 32 colors can be used in the Bob. The Bob Depth must not exceed the background depth. Specify Depth using a statement such as the following:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	myVSprite.Depth = 5; /* Allow a 32 color, 5-bitplane image. */		myVSprite.Depth = 5; /* Allow a 32 color, 5-bitplane image. */
	</syntaxhighlight>		</syntaxhighlight>
Line 216:		Line 216:
	An example of the kinds of statements that accomplish these actions (see the makeVSprite() and makeBob() examples for more details):		An example of the kinds of statements that accomplish these actions (see the makeVSprite() and makeBob() examples for more details):

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#define BOBW 1		#define BOBW 1
	#define BOBH 5		#define BOBH 5
Line 277:		Line 277:
	For example, to assure that myBob1 always appears in front of myBob2, The Before and After pointers must be initialized so that the system will always draw myBob1 after myBob2.		For example, to assure that myBob1 always appears in front of myBob2, The Before and After pointers must be initialized so that the system will always draw myBob1 after myBob2.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	myBob2.Before = &myBob1; /* draw Bob2 before drawing Bob1 */		myBob2.Before = &myBob1; /* draw Bob2 before drawing Bob1 */
	myBob2.After = NULL; /* draw Bob2 after no other Bob */		myBob2.After = NULL; /* draw Bob2 after no other Bob */
Line 294:		Line 294:
	For example:		For example:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct GelsInfo myGelsInfo = {0};		struct GelsInfo myGelsInfo = {0};
	struct VSprite dummySpriteA = {0}, dummySpriteB = {0};		struct VSprite dummySpriteA = {0}, dummySpriteB = {0};
Line 313:		Line 313:
	Two methods may be used to remove a Bob. The first method uses the RemBob() macro. RemBob() causes the system to remove the Bob during the next call to DrawGList() (or two calls to DrawGList() if the system is double-buffered). RemBob() asks the system to remove the Bob at the next convenient time. See the description of the BOBSAWAY and BOBNIX flags above. It is called as follows:		Two methods may be used to remove a Bob. The first method uses the RemBob() macro. RemBob() causes the system to remove the Bob during the next call to DrawGList() (or two calls to DrawGList() if the system is double-buffered). RemBob() asks the system to remove the Bob at the next convenient time. See the description of the BOBSAWAY and BOBNIX flags above. It is called as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Bob myBob = {0};		struct Bob myBob = {0};

Line 321:		Line 321:
	The second method uses the RemIBob() routine. RemIBob() tells the system to remove this Bob immediately. For example:		The second method uses the RemIBob() routine. RemIBob() tells the system to remove this Bob immediately. For example:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Bob myBob = {0};		struct Bob myBob = {0};
	struct RastPort rastport = {0};		struct RastPort rastport = {0};
Line 337:		Line 337:
	Once the GelsInfo list has been sorted, the Bobs in the list can be displayed by calling DrawGList(). This call should then be followed by a call to WaitTOF() if the application wants to be sure that the Bobs are rendered before proceeding. Call these functions as follows:		Once the GelsInfo list has been sorted, the Bobs in the list can be displayed by calling DrawGList(). This call should then be followed by a call to WaitTOF() if the application wants to be sure that the Bobs are rendered before proceeding. Call these functions as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct RastPort myRastPort = {0}; /* Of course, these have to be initialized... */		struct RastPort myRastPort = {0}; /* Of course, these have to be initialized... */
	struct ViewPort myViewPort = {0};		struct ViewPort myViewPort = {0};
Line 535:		Line 535:
	To find whether a Bob is to be double-buffered, the system examines the pointer named DBuffer in the Bob structure. If this pointer has a value of NULL, the system does not use double-buffering for this Bob. For example:		To find whether a Bob is to be double-buffered, the system examines the pointer named DBuffer in the Bob structure. If this pointer has a value of NULL, the system does not use double-buffering for this Bob. For example:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	myBob.DBuffer = NULL; /* do this if this Bob is NOT double-buffered */		myBob.DBuffer = NULL; /* do this if this Bob is NOT double-buffered */
	</syntaxhighlight>		</syntaxhighlight>
Line 551:		Line 551:
	To create a double-buffered Bob, execute a code sequence similar to the following:		To create a double-buffered Bob, execute a code sequence similar to the following:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Bob myBob = {0};		struct Bob myBob = {0};
	struct DBufPacket myDBufPacket = {0};		struct DBufPacket myDBufPacket = {0};

Costel Mincea: /* DBufPacket and Double-Buffering */

2020-03-01T21:21:31Z

DBufPacket and Double-Buffering

← Older revision		Revision as of 21:21, 1 March 2020
Line 543:		Line 543:
	For double-buffering, a place must be provided for the system to store the extra information it needs. The system maintains these data, and does not expect the application to change them. The DBufPacket structure consists of the following members:		For double-buffering, a place must be provided for the system to store the extra information it needs. The system maintains these data, and does not expect the application to change them. The DBufPacket structure consists of the following members:

		⚫	* BufY, BufX</br>Lets the system keep track of where the object was located "in the last frame" (as compared to the Bob structure members called oldY and oldX that tell where the object was two frames ago). BufY and BufX provide for correct restoration of the background within the currently active drawing buffer.
	BufY, BufX
⚫	Lets the system keep track of where the object was located "in the last frame" (as compared to the Bob structure members called oldY and oldX that tell where the object was two frames ago). BufY and BufX provide for correct restoration of the background within the currently active drawing buffer.

		⚫	* BufPath</br>Assures that the system restores the backgrounds in the correct sequence; it relates to the VSprite members DrawPath and ClearPath.
	BufPath
⚫	Assures that the system restores the backgrounds in the correct sequence; it relates to the VSprite members DrawPath and ClearPath.

		⚫	* BufBuffer</br>This field must be set to point to a buffer the same size as the Bob's SaveBuffer. This buffer is used to store the background for later restoration when the system moves the object. This buffer must be allocated from Chip memory.
	BufBuffer
⚫	This field must be set to point to a buffer the same size as the Bob's SaveBuffer. This buffer is used to store the background for later restoration when the system moves the object. This buffer must be allocated from Chip memory.

	To create a double-buffered Bob, execute a code sequence similar to the following:		To create a double-buffered Bob, execute a code sequence similar to the following:

Costel Mincea: /* DBufPacket and Double-Buffering */

2020-03-01T21:18:15Z

DBufPacket and Double-Buffering

← Older revision		Revision as of 21:18, 1 March 2020
Line 543:		Line 543:
	For double-buffering, a place must be provided for the system to store the extra information it needs. The system maintains these data, and does not expect the application to change them. The DBufPacket structure consists of the following members:		For double-buffering, a place must be provided for the system to store the extra information it needs. The system maintains these data, and does not expect the application to change them. The DBufPacket structure consists of the following members:

			BufY, BufX
	Lets the system keep track of where the object was located "in the last frame" (as compared to the Bob structure members called oldY and oldX that tell where the object was two frames ago). BufY and BufX provide for correct restoration of the background within the currently active drawing buffer.		Lets the system keep track of where the object was located "in the last frame" (as compared to the Bob structure members called oldY and oldX that tell where the object was two frames ago). BufY and BufX provide for correct restoration of the background within the currently active drawing buffer.

			BufPath
	Assures that the system restores the backgrounds in the correct sequence; it relates to the VSprite members DrawPath and ClearPath.		Assures that the system restores the backgrounds in the correct sequence; it relates to the VSprite members DrawPath and ClearPath.

			BufBuffer
	This field must be set to point to a buffer the same size as the Bob's SaveBuffer. This buffer is used to store the background for later restoration when the system moves the object. This buffer must be allocated from Chip memory.		This field must be set to point to a buffer the same size as the Bob's SaveBuffer. This buffer is used to store the background for later restoration when the system moves the object. This buffer must be allocated from Chip memory.

Steven Solie: /* Double-Buffering */

2015-11-06T21:24:27Z

Double-Buffering

← Older revision		Revision as of 21:24, 6 November 2015
Line 535:		Line 535:
	To find whether a Bob is to be double-buffered, the system examines the pointer named DBuffer in the Bob structure. If this pointer has a value of NULL, the system does not use double-buffering for this Bob. For example:		To find whether a Bob is to be double-buffered, the system examines the pointer named DBuffer in the Bob structure. If this pointer has a value of NULL, the system does not use double-buffering for this Bob. For example:

			<syntaxhighlight>
	<pre>
	myBob.DBuffer = NULL; /* do this if this Bob is NOT double-buffered */		myBob.DBuffer = NULL; /* do this if this Bob is NOT double-buffered */
			</syntaxhighlight>
	</pre>

	==== DBufPacket and Double-Buffering ====		==== DBufPacket and Double-Buffering ====
Line 551:		Line 551:
	To create a double-buffered Bob, execute a code sequence similar to the following:		To create a double-buffered Bob, execute a code sequence similar to the following:

			<syntaxhighlight>
	<pre>
	struct Bob myBob = {0};		struct Bob myBob = {0};
	struct DBufPacket myDBufPacket = {0};		struct DBufPacket myDBufPacket = {0};

	/* Allocate a DBufPacket for myBob same size as previous example */		/* Allocate a DBufPacket for myBob same size as previous example */
	if (NULL != (myDBufPacket.BufBuffer = AllocRaster(48, 20 * 5)))		if (NULL != (myDBufPacket.BufBuffer = IGraphics->AllocRaster(48, 20 * 5)))
	{		{
	/* tell Bob about its double buff status */		/* tell Bob about its double buff status */
	myBob.DBuffer = myDBufPacket;		myBob.DBuffer = myDBufPacket;
	}		}
			</syntaxhighlight>
	</pre>

	The example routines makeBob() and freeBob() in the animtools.c listing at the end of this article show how to correctly allocate and free a double-buffered Bob.		The example routines makeBob() and freeBob() in the animtools.c listing at the end of this article show how to correctly allocate and free a double-buffered Bob.

Steven Solie: /* Sorting and Displaying Bobs */

2015-11-06T21:23:49Z

Sorting and Displaying Bobs

← Older revision		Revision as of 21:23, 6 November 2015
Line 337:		Line 337:
	Once the GelsInfo list has been sorted, the Bobs in the list can be displayed by calling DrawGList(). This call should then be followed by a call to WaitTOF() if the application wants to be sure that the Bobs are rendered before proceeding. Call these functions as follows:		Once the GelsInfo list has been sorted, the Bobs in the list can be displayed by calling DrawGList(). This call should then be followed by a call to WaitTOF() if the application wants to be sure that the Bobs are rendered before proceeding. Call these functions as follows:

			<syntaxhighlight>
	<pre>
	struct RastPort myRastPort = {0}; /* Of course, these have to be initialized... */		struct RastPort myRastPort = {0}; /* Of course, these have to be initialized... */
	struct ViewPort myViewPort = {0};		struct ViewPort myViewPort = {0};

	SortGList(&~~amp;~~myRastPort);		IGraphics->SortGList(&myRastPort);
	DrawGList(&~~amp;~~myRastPort, &~~amp;~~myViewPort); /* Draw the elements (Bobs only) */		IGraphics->DrawGList(&myRastPort, &myViewPort); /* Draw the elements (Bobs only) */
	WaitTOF();		IGraphics->WaitTOF();
			</syntaxhighlight>
	</pre>

	{{Note\|title=Warning\|text=If your GelsInfo list contains VSprites in addition to Bobs, you must also call MrgCop() and LoadView() to make all the GELs visible. Or, under Intuition, RethinkDisplay() must be called to make all the GELs visible.}}		{{Note\|title=Warning\|text=If your GelsInfo list contains VSprites in addition to Bobs, you must also call MrgCop() and LoadView() to make all the GELs visible. Or, under Intuition, RethinkDisplay() must be called to make all the GELs visible.}}

Steven Solie: /* Removing a Bob */

2015-11-06T21:23:11Z

Removing a Bob

← Older revision		Revision as of 21:23, 6 November 2015
Line 313:		Line 313:
	Two methods may be used to remove a Bob. The first method uses the RemBob() macro. RemBob() causes the system to remove the Bob during the next call to DrawGList() (or two calls to DrawGList() if the system is double-buffered). RemBob() asks the system to remove the Bob at the next convenient time. See the description of the BOBSAWAY and BOBNIX flags above. It is called as follows:		Two methods may be used to remove a Bob. The first method uses the RemBob() macro. RemBob() causes the system to remove the Bob during the next call to DrawGList() (or two calls to DrawGList() if the system is double-buffered). RemBob() asks the system to remove the Bob at the next convenient time. See the description of the BOBSAWAY and BOBNIX flags above. It is called as follows:

			<syntaxhighlight>
	<pre>
	struct Bob myBob = {0};		struct Bob myBob = {0};

	RemBob(&~~amp;~~myBob);		RemBob(&myBob);
			</syntaxhighlight>
	</pre>

	The second method uses the RemIBob() routine. RemIBob() tells the system to remove this Bob immediately. For example:		The second method uses the RemIBob() routine. RemIBob() tells the system to remove this Bob immediately. For example:

			<syntaxhighlight>
	<pre>
	struct Bob myBob = {0};		struct Bob myBob = {0};
	struct RastPort rastport = {0};		struct RastPort rastport = {0};
	struct ViewPort viewport = {0};		struct ViewPort viewport = {0};

	RemIBob(&~~amp;~~myBob, &~~amp;~~rastport, &~~amp;~~viewport);		IGraphics->RemIBob(&myBob, &rastport, &viewport);
			</syntaxhighlight>
	</pre>

	This causes the system to erase the Bob from the drawing area and causes the immediate erasure of any other Bob that had been drawn subsequent to (and on top of) this one. The system then unlinks the Bob from the system GEL list. To redraw the Bobs that were drawn on top of the one just removed, another call to DrawGList() must be made.		This causes the system to erase the Bob from the drawing area and causes the immediate erasure of any other Bob that had been drawn subsequent to (and on top of) this one. The system then unlinks the Bob from the system GEL list. To redraw the Bobs that were drawn on top of the one just removed, another call to DrawGList() must be made.

Steven Solie: /* Adding a Bob */

2015-11-06T21:21:55Z

Adding a Bob

← Older revision		Revision as of 21:21, 6 November 2015
Line 294:		Line 294:
	For example:		For example:

			<syntaxhighlight>
	<pre>
	struct GelsInfo myGelsInfo = {0};		struct GelsInfo myGelsInfo = {0};
	struct VSprite dummySpriteA = {0}, dummySpriteB = {0};		struct VSprite dummySpriteA = {0}, dummySpriteB = {0};
Line 303:		Line 303:
	** article for a more complete initialization of the Gel system		** article for a more complete initialization of the Gel system
	*/		*/
	InitGels(&~~amp;~~dummySpriteA, &~~amp;~~dummySpriteB, &~~amp;~~myGelsInfo);		IGraphics->InitGels(&dummySpriteA, &dummySpriteB, &myGelsInfo);

	/* Initialize the Bob members here, then AddBob() */		/* Initialize the Bob members here, then AddBob() */
	AddBob(&~~amp;~~myBob, &~~amp;~~rastport);		IGraphics->AddBob(&myBob, &rastport);
			</syntaxhighlight>
	</pre>

	=== Removing a Bob ===		=== Removing a Bob ===

Steven Solie: /* Specifying the Drawing Order */

2015-11-06T21:21:11Z

Specifying the Drawing Order

← Older revision		Revision as of 21:21, 6 November 2015
Line 277:		Line 277:
	For example, to assure that myBob1 always appears in front of myBob2, The Before and After pointers must be initialized so that the system will always draw myBob1 after myBob2.		For example, to assure that myBob1 always appears in front of myBob2, The Before and After pointers must be initialized so that the system will always draw myBob1 after myBob2.

			<syntaxhighlight>
	<pre>
	myBob2.Before = &~~amp;~~myBob1; /* draw Bob2 before drawing Bob1 */		myBob2.Before = &myBob1; /* draw Bob2 before drawing Bob1 */
	myBob2.After = NULL; /* draw Bob2 after no other Bob */		myBob2.After = NULL; /* draw Bob2 after no other Bob */
	myBob1.After = &~~amp;~~myBob2; /* draw Bob1 after drawing Bob2 */		myBob1.After = &myBob2; /* draw Bob1 after drawing Bob2 */
	myBob1.Before = NULL; /* draw Bob1 before no other Bob */		myBob1.Before = NULL; /* draw Bob1 before no other Bob */
			</syntaxhighlight>
	</pre>

	As the system goes through the GelsInfo list, it checks the Bob's After pointer. If this is not NULL, it follows the After pointer until it hits a NULL. Then it starts rendering the Bobs, going back up the Before pointers until it hits a NULL. Then it continues through the GelsInfo list. So, it is important that ''all'' Before and After pointers of a group properly point to each other.		As the system goes through the GelsInfo list, it checks the Bob's After pointer. If this is not NULL, it follows the After pointer until it hits a NULL. Then it starts rendering the Bobs, going back up the Before pointers until it hits a NULL. Then it continues through the GelsInfo list. So, it is important that ''all'' Before and After pointers of a group properly point to each other.

Steven Solie: /* PlaneOnOff */

2015-11-06T21:20:45Z

PlaneOnOff

← Older revision		Revision as of 21:20, 6 November 2015
Line 257:		Line 257:
	/* Create the Sprite collision mask in the VSprite structure */		/* Create the Sprite collision mask in the VSprite structure */
	IGraphics->InitMasks(&myVSprite);		IGraphics->InitMasks(&myVSprite);
	<syntaxhighlight>		</syntaxhighlight>

	=== Bob Priorities ===		=== Bob Priorities ===

Steven Solie: /* PlaneOnOff */

2015-11-06T21:20:29Z

PlaneOnOff

← Older revision		Revision as of 21:20, 6 November 2015
Line 216:		Line 216:
	An example of the kinds of statements that accomplish these actions (see the makeVSprite() and makeBob() examples for more details):		An example of the kinds of statements that accomplish these actions (see the makeVSprite() and makeBob() examples for more details):

			<syntaxhighlight>
	<pre>
	#define BOBW 1		#define BOBW 1
	#define BOBH 5		#define BOBH 5
Line 222:		Line 222:

	/* Data definition from example layout */		/* Data definition from example layout */
	~~WORD~~ chip BobData[]=		uint16 chip BobData[]=
	{		{
	0xFFFF, 0x300C, 0x0FF0, 0x03C0, 0x0180,		0xFFFF, 0x300C, 0x0FF0, 0x03C0, 0x0180,
Line 229:		Line 229:

	/* Reserve space for the collision mask for this Bob */		/* Reserve space for the collision mask for this Bob */
	~~WORD~~ chip BobCollision[BOBW * BOBH];		uint16 chip BobCollision[BOBW * BOBH];

	myVSprite.Width = BOBW; /* Image is 16 pixels wide (1 word) */		myVSprite.Width = BOBW; /* Image is 16 pixels wide (1 word) */
Line 243:		Line 243:
	/* binary 0000, means colors 1, 4, and 5 will be used.		/* binary 0000, means colors 1, 4, and 5 will be used.
	* binary 0010 would mean colors 3, 6, and 7.		* binary 0010 would mean colors 3, 6, and 7.
	* ~~"~~ 1000 ~~"~~ ~~"~~ ~~"~~ 9, C, and D.		* " 1000 " " " 9, C, and D.
	* ~~"~~ 1010 ~~"~~ ~~"~~ ~~"~~ B, E, and F.		* " 1010 " " " B, E, and F.
	*/		*/
	myVSprite.PlaneOnOff = 0x00;		myVSprite.PlaneOnOff = 0x00;
Line 256:		Line 256:

	/* Create the Sprite collision mask in the VSprite structure */		/* Create the Sprite collision mask in the VSprite structure */
	InitMasks(&~~amp;~~myVSprite);		IGraphics->InitMasks(&myVSprite);
			<syntaxhighlight>
	</pre>

	=== Bob Priorities ===		=== Bob Priorities ===