home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / Blitting Class Library / BCL Manual
Encoding:
Text File  |  1995-11-18  |  7.1 KB  |  88 lines  |  [TEXT/ttxt]

  1. The Blitting Class Library Manual
  2. Copyright © 1995, Macneil Shonle. All rights reserved.
  3.  
  4. Contents
  5.  Introduction
  6.  Use of BufferAccessor
  7.  What is to come
  8.  Frequently Asked Questions
  9.  Notes on Style
  10.  In Closing
  11.  
  12. Introduction
  13. The following component explained here is the evolution of some direct blitting classes I had made for my own personal use. As I used the classes more and more I was able to see what was needed in the classes, and what wasn’t. The result was a much simpler and cleaner design that can be useful to anyone interested in speeding up their graphics routines on the Macintosh.
  14.  
  15. If you want to directly access a GWorld (an offscreen graphics world), all you have to do is supply a pointer to it in the constructor for a GWorldAccessor object. Take a look at the following code, it will directly access the GWorld’s pixel-map to draw a black dot at coordinate (12, 16), that is, assuming that myGWorld is pointing to a GWorld created with the system’s NewGWorld routine:
  16.  
  17.     GWorldAccessor gworldBuff(myGWorld);
  18.     gworldBuff.setPixel(12, 16, 0xFF);
  19.  
  20. Previously, the same class that provided access to the pixel-map also created it. This looked simpler on the outside, but was too limiting to users of other frameworks and put too much complexity in one class. For users who liked the encapsulation of the GWorld (so they didn’t have to worry about calling NewGWorld and DisposeGWorld), I have provided a set of SecureMacPorts to be used:
  21.  
  22.     Rect bounds = {0, 0, 400, 400};
  23.     SecureGWorld gworld(bounds);
  24.     
  25.     GWorldAccessor gworldBuff(gworld);
  26.     // ...
  27.  
  28. Use of BufferAccessor
  29. The power of polymorphism can be shown by having a series of blitting functions use a BufferAccessor& as their parameter. For example, look at this (inefficient) function that fills the parameter’s pixel-map to black:
  30.  
  31.     void Flood(BufferAccessor& buff)
  32.     {
  33.         for (PixelCord y=0; y<buff.height(); y++)
  34.             for (PixelCord x=0; x<buff.width(); x++)
  35.                 buff.setPixel(x, y, 0xFF);
  36.     }
  37.  
  38. Note that this may be a window on the screen or a GWorld, the code doesn’t care and works either way. Now take a look at a more efficient version:
  39.  
  40.     void Flood(BufferAccessor& buff)
  41.     {
  42.         MMUModeSwapper swapTo(buff.use32Bit());
  43.     
  44.         FourPixelsPtr dest = (FourPixelsPtr)buff.baseAddr();
  45.         RowBytes rowSkip = buff.rowBytes() - buff.width();
  46.         PixelCord height = buff.height()
  47.         PixelCord width = buff.width() / 4;
  48.     
  49.         for (PixelCord y=0; y<height; y++) {
  50.             for (PixelCord x=0; x<width; x++)
  51.                 *dest++ = 0xFFFFFFFF;
  52.             dest = FourPixelsPtr(PixelPtr(dest) + rowSkip);
  53.         }
  54.     }
  55.  
  56. This can be optimized even more, but the use and simplicity of the accessors should be clear now. You may have noticed the use of the MMUModeSwapper class (from <MMUModeSwapper.h>). It uses the “resource acquisition is initialization” technique (see 9.4 of Stroustrup). When the object is initialized, the constructor puts the machine into the correct addressing mode. It is up to the destructor to return the machine back to the previous state. Similar to the MMUModeSwapper, there is a GWorldSetter. This technique is useful because (1) it reduces the amount of code to be writen, in a clear and elegant manner; (2) it ensures that the state will always be returned, important for when an exception is thrown; and (3) a programmer might forget to return the state back otherwise.
  57.  
  58. The header <PixelTypes.h> is useful if ever the bytes-per-integral-type change in an implementation; that way, all of the code that will have to be rewriten would be in one place (the header).
  59.  
  60. What is to come
  61. In the “Blitting Class Library” folder, there is a folder named “Plans,” which includes a sample of what the ImageCopier class will look like. This should be useful for programs that can change their mind at run time about which copy method to use (CopyBits vs. direct). In an informal test I did on the PowerPC, the CopyBits routine took 80% of all processor time. I replaced all calls to CopyBits with a blitter of my own, and total processor time dropped to 60%, this can be “optimized” even more.
  62.  
  63. Collision detection will be added into the sprite classes. A class for fading the screen is also planned, and I’ll probably throw in some functions for hiding the menu bar, just for sport.
  64.  
  65. Frequently Asked Questions
  66. • What is Blitting?
  67.  
  68. The term “blit” came from the PDP-11 instruction BLT (BLock Transfer). This instruction was used to move graphics from one place to the other, back in the old days. Now blit has a more general meaning and implies graphics operations. For example, something that draws sprites on the screen would be a sprite blitter.
  69.  
  70. • What is a Sprite?
  71.  
  72. A sprite is any moving object on the screen that has a mask.
  73.  
  74. • Why can’t the code compile? Something is wrong with the headers, I think.
  75.  
  76. Move the “Blitting Class Library” folder to the system level (i.e. the folder with the compiler in it). That’s because I use <name.h> instead of "name.h". That’s all.
  77.  
  78. Notes on Style
  79. The style of the code has changed completly since the CDirectBlit release of these classes (you can call this  the BufferAccessor release). Support for exceptions have been brought in, and everything is much more atomic (the two changes went hand-in-hand). It was much harder to design this version than past versions, but it was much simpler to implement.
  80.  
  81. On a less important note: The naming coventions have been changed, and no longer use PowerPlant-like prefixes. The name CDirectBlit was a misnomer if I ever saw one, and was briefly changed to DirectBuffer before the design changed to the current accessor version. I also changed the member-function naming convention so that the first letter of each function is in lower case, which matches the familiar style I’ve seen in the books: Advanced C++ Programming Styles and Idioms and C++ FAQs, and in Smalltalk. The brace placement style has been changed to the more traditional K&R style. I still use the “#ifndef/#define/#endif” technique to avoid the inclusion of a header file twice, which is less implementation dependant than “#pragma once” is.
  82.  
  83. In Closing
  84. These classes have been made to aid blitting code for those who do not want to change their project to a whole new library when all they want to do is just get the base address of a GWorld. These are the people I had in mind while writing this code. If you have a GWorld already made with PowerPlant, you can still benefit with direct access, and with my classes.
  85.  
  86. Finally: I need more input from people who have downloaded these classes. Do you like them? Do you hate them? Is there something you wished they had or did or didn’t do? Any input will help me. Send all comments via email to: macneils@aol.com.
  87.  
  88. Note Feel free to upload this code anywhere, but only the original archive. You may change the code for your own uses (making functions inline, et cetera…), but you are not given permission to distribute it in the changed form. Use the Blitting Class Library, or parts of it, at your own risk. If the libarary is used in a project, you are not obligated to give credit, but it would be nice if you were to. The code is free, enjoy!