Return to bitblt CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / new / X / libibm / doc

Annotation of 43BSDTahoe/new/X/libibm/doc/bitblt, revision 1.1

1.1     ! root        1: .so mod.ms
        !             2: .ce 1
        !             3: .ls 2
        !             4: \fBOverview of the IRIS bitblt Primitive\fP
        !             5: .sp 2.5
        !             6: By Daniel Stone, Brown University/IRIS
        !             7: .sp 1
        !             8: .NH 1
        !             9: Introduction
        !            10: .sp
        !            11: .PP
        !            12: The IRIS bitblt primitive (here after referred to as "bitblt") was derived
        !            13: after researching the following papers and books, \fBBitmap Graphics
        !            14: Siggraph'84 Course Notes\fP, \fBSmalltalk-80 The Language and Its
        !            15: Implementation\fP "The Graphics Kernel" and \fBInside Macintosh\fP "QuickDraw".
        !            16: If one has any questions or does not know what a bitblt is, one should
        !            17: look over these resources.  People who know what a bitblt primitive does
        !            18: may want to skip to the "Introduction Summary" or the "Bitblt Interface"
        !            19: section of this paper.  Below I will describe, in general terms where the
        !            20: bitblt program came from and how it works.
        !            21: .PP
        !            22: "bitblt" comes from BIT-boundary BLock Transfer.  It is called
        !            23: a "RasterOp" by Newman and Sproull.
        !            24: It originated from the \fIFrame Buffer\fP model or \fIRaster Graphics\fP.
        !            25: The typical raster graphics screen has an array of memory (called a frame
        !            26: buffer) and hardware that scans through that memory
        !            27: and maps it onto the tube to create an image.
        !            28: A raster tube is made up of a two dimensional array of tiny dots of light 
        !            29: called picture elements.
        !            30: Pixel (or pel) is short for picture elements.
        !            31: Different tubes have different amounts of memory
        !            32: associated with each "pixel" on the screen. 
        !            33: Color and gray scale screens may have frame buffers
        !            34: where 8 bits represent a pixel on the screen.
        !            35: Black and white (monochrome) screens have frame
        !            36: buffers where each bit represents a pixel on
        !            37: the screen.  Because of this attribute, these screens are sometimes
        !            38: referred to as \fIbitmap\fP displays.
        !            39: Bitblt was designed to work on bitmap displays.
        !            40: Because one pixel is represented by one bit, pixel
        !            41: and bit are used interchangeably in this paper.
        !            42: The bitmap (or frame buffer memory) may be
        !            43: addressable on bit, byte or WORD (16 bits or
        !            44: SHORT) boundaries depending on the screen hardware.
        !            45: Most displays (all that I've worked with) allow access
        !            46: on byte or short boundaries.
        !            47: On each screen, the line of pixels (or bits) across the screen (or
        !            48: across the frame buffer or bitmap) is called a
        !            49: \fIscanline\fP.
        !            50: A screen that is 768 bits high by 1024 bits wide has 768 scanlines each
        !            51: of which is 1024 bits (or 64 shorts) wide.
        !            52: .PP
        !            53: Bitblt arose from the need to move an image on the
        !            54: screen from one spot to another.
        !            55: Some screens allow the user to address individual bits or address
        !            56: bytes or shorts in the frame buffer.   Others allow byte or short
        !            57: access only. The bitblt primative receives arguments
        !            58: as if the screen has bit addressing
        !            59: and deals with the screen in what ever addressing
        !            60: mode it has.
        !            61: So bitblt works on frame buffer memory that is byte or short addressable.
        !            62: This has the effect of hiding the screen hardware from the user.
        !            63: Bitblt is the "output primitive", it is the only function needed to
        !            64: deal with the screen.  It can be used to draw lines, characters, images,
        !            65: shapes, and anything else.
        !            66: .PP
        !            67: If bitblt works on frame buffer memory that is byte or short addressable
        !            68: then it should (and does) work on ANY memory that is byte or short
        !            69: addressable.
        !            70: So bitblt can act on bitmaps in main memory as well as on the frame buffer.
        !            71: But why would one want to use bitblt on "off-screen" memory?
        !            72: There are many reasons and here are a few common ones.
        !            73: An application may want to store fonts off screen and then "blt" them to
        !            74: the screen as needed.  An application may want to store menus, icons,
        !            75: windows, and any other window manager items that would have to be re-created
        !            76: \fIevery time\fP they were used.
        !            77: An application may wish to show animation by  storing all sequences then
        !            78: using bitblt to put them on and off the screen quickly.
        !            79: Basicly bitmaps are a general representation of an image, and
        !            80: bitblt is a general primitive for manipulating them.
        !            81: .PP
        !            82: Bitblt not only copies the source to the destination but a user can also
        !            83: specify different bit combination rules like and, or, xor etc..
        !            84: Bitblt takes the source, combines it with the destination according to the
        !            85: combination rule and puts it back in the destination.
        !            86: .PP
        !            87: Another bitmap operation needed is the ability to replicate a specified source
        !            88: all over a bit specified area in the destination. (By "bit specified area"
        !            89: I mean there is a rectangular set of bits in the destination which are to
        !            90: be changed.  There may also be a set of bits surrounding this area and it
        !            91: is not to be changed.) This would allow a user to
        !            92: easily set or blank part or all of a bitmap.
        !            93: The source could be all white
        !            94: or all black or some pattern and it would be "tiled" in a bit specified area
        !            95: of the destination.
        !            96: ("Tiled", as in taking these little squares of tile all with the same pattern
        !            97: on them and lining them up on your bathroom floor or wall.)
        !            98: A tile in the bitblt program is a specified size of 16 x 16 bits which is
        !            99: 16 unsigned shorts.  The user specifies a tile combination rule (like
        !           100: TileCopy or TileOr, etc.) and a tile and (after specifying other parameters)
        !           101: calls the bitblt function.  Bitblt uses the tile as the source and replicates
        !           102: it all over the specified area in the destination.  How it replicates the
        !           103: tile on the destination is very important.  Think of the destination as being
        !           104: totally covered by the tile so that the first bit in the tile is sitting ON
        !           105: the first bit in the destination. So you've rolled the tile dough onto the
        !           106: destination and now you cookie cut this dough with the bit specified area
        !           107: in the destination and peel away everything on the outside of the cookie
        !           108: cutter.  This leaves the tile where you want it. In other words the
        !           109: tile is lined up with the origin of the destination.
        !           110: .PP
        !           111: The last necessary bitmap operation is being able to copy a source or tile
        !           112: to the destination through a bitmap.  For example, say you want the letter
        !           113: "A" stenciled onto your new lawn mower.
        !           114: You take a can of black spray paint, the letter "A" in a stencil,
        !           115: place it on your lawn mower and spray.  The lawn mower now has a
        !           116: black letter "A" on it.  In this case, the spray paint is a black tile,
        !           117: the letter
        !           118: "A" stencil is the masking bitmap and the lawn mower is the destination bitmap.
        !           119: .sp 1
        !           120: .NH 2
        !           121: Introduction Summary
        !           122: .sp
        !           123: .IP 1.
        !           124: Bitblt is designed to work on monochrome
        !           125: "bitmapped" displays which are byte or short
        !           126: addressable.
        !           127: .sp .5
        !           128: .IP 2.
        !           129: Bitblt allows the user to specify in BIT addressable
        !           130: form what bits in a source bitmap are to be copied
        !           131: to a bit specified area in a destination bitmap.
        !           132: The user sees a two dimensional array of bits, not
        !           133: an array of bytes or shorts.
        !           134: .sp .5
        !           135: .IP 3.
        !           136: A bitmap is a general term for an allocated area
        !           137: of memory that is acted on by bitblt. The bitmap
        !           138: may be in main memory or it may be the frame buffer.
        !           139: .sp .5
        !           140: .IP 4.
        !           141: A scanline is a line of pixels (or bits) across a bitmap.
        !           142: .IP 5.
        !           143: Bitblt is the lowest level graphics primitive on
        !           144: which all graphics output is based.
        !           145: .IP 6.
        !           146: Bitblt works on ALL memory that is byte or short addressable.
        !           147: .sp
        !           148: .LP
        !           149: Advantages of bitblt:
        !           150: .IP 1.
        !           151: One general bitmap interface to deal with.
        !           152: .IP 2.
        !           153: Doing all raster manipulations in one primitive,
        !           154: only one set of code to change when improvements are thought of.
        !           155: .IP 3.
        !           156: All applications benefit from any improvements.
        !           157: .IP 4.
        !           158: Portable.
        !           159: .sp
        !           160: .LP
        !           161: Disadvantages of bitblt:
        !           162: .IP 1.
        !           163: For absolute speed, certain functions, like fonts,
        !           164: may have to be special cased.
        !           165: .sp 2
        !           166: .NH 1
        !           167: Bitblt Interface
        !           168: .sp 1
        !           169: .LP
        !           170: To copy a set of bits from source to destination the bitblt function
        !           171: needs to have certain information.
        !           172: .sp .5
        !           173: .IP 1.
        !           174: It needs the address of the source bitmap (if the combination rule is a
        !           175: "source" rule).
        !           176: .IP 2.
        !           177: It needs the address of the destination bitmap.
        !           178: .IP 3.
        !           179: It needs to know the location of the bits within the source
        !           180: bitmap which are to be copied.
        !           181: .IP 4.
        !           182: It needs to know the location of bits within the destination
        !           183: bitmap which are to receive the source.
        !           184: .IP 5.
        !           185: It needs to know how to combine the source with the
        !           186: destination.  Ex. COPY, OR, XOR, AND, etc. the
        !           187: source to the destination,
        !           188: .sp .5
        !           189: .LP
        !           190: Other useful things the bitblt function does:
        !           191: .sp .5
        !           192: .IP 6.
        !           193: Replicate a special type of source all over the
        !           194: destination - (Tiles or Textures or Patterns.)
        !           195: .IP 7.
        !           196: Clip down the source and destination to a clipping area.
        !           197: .IP 8.
        !           198: Copy the source to the destination through a mask.  (Like a stencil.)
        !           199: .LP
        !           200: The geometry and structures involved must be discussed first before the
        !           201: actual interface structure is given in detail.
        !           202: .NH 2
        !           203: Geometry and Structures
        !           204: .ls 2
        !           205: .PP
        !           206: The bitblt function uses the "infinitely thin" coordinate system.  In this
        !           207: system there are infinitely thin lines running \fIbetween\fP each pixel
        !           208: on a bitmap. (See Siggraph'84 course notes or Inside Macintosh as
        !           209: referenced above.)  The pixels or bits are between the
        !           210: points on the grid.  A rectangle that is H points wide and
        !           211: V points tall encloses H x V bits.
        !           212: Other coordinate systems (like X) say that 
        !           213: the points on the grid \fIare\fP the pixels.
        !           214: This is important when discussing rectangles.  For example, say we
        !           215: have a rectangle whose origin is 1,2 and whose width is 2 \fIpixels\fP wide
        !           216: and its height is 3 \fIpixels\fP high.
        !           217: Using the infinitely thin coordinate system the bottom right
        !           218: corner of this rectangle would be 1+2,2+3 = \fI3,5\fP and would encompass
        !           219: 2 x 3 = 6 bits.
        !           220: Note that because of the coordinate system there are bits either on the outside
        !           221: or on the inside of the rectangle.  Using the other coordinate system,
        !           222: the bottom right corner of the this rectangle would be 1+2-1,2+3-1 = \fI2,4\fP.
        !           223: Why? Because this coordinate system is \fIinclusive\fP, so 1 through \fIand
        !           224: including\fP 2 is 2 bits and 2 through \fIand including\fP 4 is 3 bits.
        !           225: I chose the infinitely thin coordinate system because I thought it was less
        !           226: confusing but different people like different things.
        !           227: .PP
        !           228: Three structures were used to define the basic graphic entities:
        !           229: rectangles, bitmaps, and tiles, that bitblt must deal with.
        !           230: The Siggraph'84 Course Notes describe four structures that they used
        !           231: to implement their slow bitblt function.  One of them, the Point structure,
        !           232: I found useless.  The others I used but modified a bit.
        !           233: A rectangle I defined as 4 shorts:
        !           234: .DS
        !           235: typedef struct Blt_Rectangle {
        !           236:        short origin_y;
        !           237:        short origin_x;
        !           238:        short corner_y;
        !           239:        short corner_x;
        !           240: }
        !           241: .DE
        !           242: .LP
        !           243: Because a rectangle uses shorts, each coordinate has a range of
        !           244: -32768,-32768 to 32767,32767.
        !           245: .PP
        !           246: A bitmap is defined as an unsigned short pointer which points to
        !           247: the actual data (usually an array of unsigned shorts which \fImust
        !           248: be short aligned\fP), a rectangle which
        !           249: is the bounding rectangle for that data, and a short integer
        !           250: which is the number of shorts wide the bitmap is. (Very similar to Inside
        !           251: Macintosh structure.)
        !           252: .DS
        !           253: typedef struct Blt_Bitmap {
        !           254:        unsigned short *base;
        !           255:        Blt_Rectangle rect;
        !           256:        short nshorts;
        !           257: } Blt_Bitmap;
        !           258: .DE
        !           259: .LP
        !           260: Base points to an array of unsigned shorts which
        !           261: is the data that makes up the bitmap.  However nshorts is what
        !           262: gives "base", the array of unsigned shorts, a sort of 2 dimensional quality
        !           263: because this arbitrary array is now broken up into x number of segments each
        !           264: of which has "nshorts" number of shorts in it.
        !           265: Each of these segments is called a scanline.
        !           266: Previously I referred to a scanline as a line of pixels across the screen.
        !           267: (See Introduction.)  Now I would like to generalize and call a scanline
        !           268: a line of pixels (or bits) across an arbitrary bitmap.
        !           269: For example, lets say "base" points to an array of 24 unsigned shorts.
        !           270: If "nshorts" was 3 then there would be 8 scanlines, 3 shorts each.
        !           271: If "nshorts" was 4 then there would be 6 scanlines, 4 shorts each.
        !           272: "rect" could be anything as long as (rect.corner_x - rect.origin_x (the width))
        !           273: <= (nshorts * 16) and (rect.corner_y - rect.origin_y (the height)) <=
        !           274: (the size of the array(24) / nshorts)
        !           275: .PP
        !           276: The third structure is the tile structure also called the 
        !           277: Texture structure in the Siggraph course notes and referred to as
        !           278: a Pattern structure in Inside Macintosh.  It is an array of
        !           279: 16 unsigned shorts so it forms a 16 by 16 bit tile.  Note
        !           280: a Pattern in Inside Macintosh is only 8 by 8 bits but its the
        !           281: same idea.
        !           282: .DS
        !           283: typedef struct Blt_Tile {
        !           284:        unsigned short tile[TILE_SIZE];
        !           285: } Blt_Tile;
        !           286: .DE   
        !           287: .LP
        !           288: When a tile is put on a bitmap it is aligned to the bitmap's
        !           289: origin (top left) corner.  This is done so that the same tile drawn in
        !           290: different places on the same bitmap will line up.
        !           291: .NH 2
        !           292: The Interface Structure
        !           293: .PP
        !           294: The bitblt function returns -1 if a bad pointer was found or
        !           295: something was wrong, 0 if the width or height of the bitblt
        !           296: turned out to be less than zero and 1 if everything went ok.
        !           297: It also has a global Blt_Rectangle called change_rect which
        !           298: contains the final area changed by the bitblt function.  At first this
        !           299: was only used for debugging purposes but now it is used for the
        !           300: ACIS Experimental Display (Viking).
        !           301: Because bit block transfer programs must be fast, many internal routines
        !           302: have been converted to macros.
        !           303: .LP
        !           304: The bitblt routine receives a pointer to a Blt_userdata (BLT in X) structure.
        !           305: This structure looks like this:
        !           306: .sp .5
        !           307: .QP
        !           308: \fBBlt_Bitmap src_bitmap\fP - Bitmap to be copied from.
        !           309: .sp .5
        !           310: .QP
        !           311: \fBBlt_Rectangle src_rect\fP - Specifies the area in the
        !           312: src_bitmap to be used, its coordinates are in the
        !           313: source bitmap's coordinate system.
        !           314: .sp .5
        !           315: .QP
        !           316: \fBBlt_Bitmap dst_bitmap\fP - Bitmap to be changed.
        !           317: .sp .5
        !           318: .QP
        !           319: \fBBlt_Rectangle dst_rect\fP - Specifies the area in the
        !           320: dst_bitmap to be changed.  Its coordinates are in
        !           321: the destination bitmap's coordinate system.
        !           322: .sp .5
        !           323: .QP
        !           324: \fBBlt_Rectangle clp_rect\fP - Another rectangle to clip
        !           325: against if the BLT_CLIPON bit in blt_flags is a 1.
        !           326: If the BLT_CLIPON bit is 0 then clp_rect is never
        !           327: accessed. (In other words it does not have to be set to
        !           328: anything.) Its coordinates are also in the destination
        !           329: bitmap's coordinate system.
        !           330: .sp .5
        !           331: .QP
        !           332: \fBBlt_Tile *tile_ptr\fP - The tile (or pattern or
        !           333: texture... this is a 16x16 bit area) to be used if the
        !           334: combination rule uses a tile.
        !           335: .sp .5
        !           336: .QP
        !           337: \fBBlt_Bitmap msk_bitmap\fP - Masking bitmap, which is
        !           338: like regions in the Macintosh world.  This is hard to
        !           339: explain.  A masking bitmap is kind of like a
        !           340: stencil, for every 1 or on bit in the mask bitmap the bit
        !           341: operation is allowed.  Where there are 0 or off bits in the
        !           342: mask bitmap the destination will remain the same.
        !           343: To use this feature, the BLT_MASKON bit in blt_flags
        !           344: must be 1.  The setup for this structure requires
        !           345: some explanation.
        !           346: .QP
        !           347: - "base" points to the actual data used for the mask.
        !           348: .QP
        !           349: - "nshorts" is the number of shorts wide the bitmap is.
        !           350: (These two are just like normal bitmaps.)
        !           351: .QP
        !           352: - "rect" is NOT just any bounding rectangle, its
        !           353: coordinates have to be in the destination bitmap's
        !           354: coordinate system.  Furthermore, this bitmap
        !           355: is expected to line up with the dst_rect or
        !           356: clp_rect depending on what you want.  Typically
        !           357: this is set equal to either dst_rect or clp_rect.
        !           358: An example of this in use is:
        !           359: You have a tiny bitmap that contains the image of
        !           360: the character "A".  It is 1 short wide (16 bits) by
        !           361: 12 scan lines high.  It is in the Blt_Bitmap struct
        !           362: char_A.
        !           363: We set comb_rule equal to a tile rule (like
        !           364: TileCopy), set the dst_bitmap equal to
        !           365: bitblt_screen (see Examples at end of paper), turn off/on
        !           366: clipping, set blt_flags or/equal (|=) to BLT_MASKON,
        !           367: set up the dst_rect with say 10,10,22,22, set the
        !           368: tile_ptr equal to a tile that is all black and now
        !           369: we set up msk_bitmap.  msk_bitmap.base = char_A.base,
        !           370: msk_bitmap.nshorts = char_A.nshorts, and
        !           371: msk_bitmap.rect = dst_rect or clip_rect depending
        !           372: on whether or not clipping was on and what you wanted.
        !           373: Now the character "A" is "stenciled" onto the destination at 10,10,22,22.
        !           374: (Note the normal thing to do would be to
        !           375: copy this "A" to the screen every time "SHIFT a"
        !           376: is hit (using char_A as the source and bitblt_screen
        !           377: as the destination), but in this example we were
        !           378: different to make a point.)
        !           379: .sp .5
        !           380: .QP
        !           381: \fBshort comb_rule\fP - Combination rule to be used. If
        !           382: this rule is a SOURCE combination rule then tile_ptr
        !           383: is never accessed. (Again, In other words it does not
        !           384: have to be set to anything.)  If this rule is a
        !           385: tile rule then src_bitmap and src_rect are never
        !           386: accessed.
        !           387: .sp .5
        !           388: .QP
        !           389: \fBshort blt_flags\fP - A bit on means do a certain extra
        !           390: operation.  For example if the first bit is on (the
        !           391: BLT_CLIPON bit) then do clipping.  If the BLT_MASKON
        !           392: bit is on then the masking bitmap is used.  Both
        !           393: of these can be set at the same time. (of course.)
        !           394: (BLT_MASKON | BLT_CLIPON)
        !           395: .sp
        !           396: .LP
        !           397: The actual C structure looks like this:
        !           398: .DS
        !           399: typedef struct {
        !           400:        Blt_Bitmap      src_bitmap;
        !           401:        Blt_Rectangle   src_rect;
        !           402:        Blt_Bitmap      dst_bitmap;
        !           403:        Blt_Rectangle   dst_rect;
        !           404:        Blt_Rectangle   clp_rect;
        !           405:        Blt_Tile        *tile_ptr;
        !           406:        Blt_Bitmap      msk_bitmap;
        !           407:        short           comb_rule;
        !           408:        short           blt_flags;
        !           409: } Blt_userdata;
        !           410: typedef Blt_userdata BLT;
        !           411: .DE
        !           412: .LP
        !           413: Flags blt_flags could be:
        !           414: .DS
        !           415:  #define BLT_CLIPON      0x1
        !           416:  #define BLT_MASKON      0x2
        !           417: .DE
        !           418: .NH
        !           419: Examples
        !           420: .sp
        !           421: .LP
        !           422: Here is an example of setting up a Blt_Bitmap structure where the hardware
        !           423: screen address is 0xF4D80000 and the visible screen is 1024 bits wide and
        !           424: 768 bits high:
        !           425: .sp .5
        !           426: .DS
        !           427: bitblt_screen.base = (unsigned short *)0xF4D80000;
        !           428: bitblt_screen.rect.origin_x = 0;
        !           429: bitblt_screen.rect.origin_y = 0;
        !           430: bitblt_screen.rect.corner_x = 1024;
        !           431: bitblt_screen.rect.corner_y = 768;
        !           432: bitblt_screen.nshorts = (1024 + 15)/16;
        !           433: .DE
        !           434: .LP
        !           435: Note the + 15 is not needed in this case, but the width may not always be
        !           436: on a short boundary and + 15 rounds it up.
        !           437: Also the rectangle could have a different origin and does not have to take
        !           438: up the whole screen (although that would be silly) It may be like this:
        !           439: .DS
        !           440: bitblt_screen.rect.origin_x = 300;
        !           441: bitblt_screen.rect.origin_y = 300;
        !           442: bitblt_screen.rect.corner_x = 1324;
        !           443: bitblt_screen.rect.corner_y = 1068;
        !           444: .DE
        !           445: .LP
        !           446: or use 1/4 of the screen:
        !           447: .DS
        !           448: bitblt_screen.rect.origin_x = 0;
        !           449: bitblt_screen.rect.origin_y = 0;
        !           450: bitblt_screen.rect.corner_x = 256;
        !           451: bitblt_screen.rect.corner_y = 192;
        !           452: .DE
        !           453: .LP
        !           454: Note bitblt_screen.nshorts \fImust\fP still be (1024 + 15)/16 even though the
        !           455: rectangle is smaller.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.