home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d7xx / d761 / blitt.lha / Blitt / manual < prev    next >
Text File  |  1992-11-21  |  11KB  |  280 lines
  1.  
  2. /*________________________________________________________________________
  3.  |                                                                        |
  4.  |    blitter.c v1.0  - © 1992  Paul Juhasz                               |
  5.  |                                                                        |
  6.  |      Started:    July, 92                                              |
  7.  |________________________________________________________________________*/
  8.  
  9.  
  10.  
  11.  
  12.        General:
  13.        --------
  14.  
  15.        Blitt © 92, is a utility to help programmers to experimentally find
  16.    Mask / MinTerm values for the BlitBitMap() / BlitMaskBitMapRastPort()
  17.    commands in 'C' or their equivalents in assembler. It can equally be
  18.    used for some graphic effects that may not be available otherwise.
  19.    Blitt was written on a ½-meg A1000 with one external drive, using the
  20.    Lattice C V3.03 compiler. It is entirely independent, just copy the
  21.    program, both pictures ( scribble/usascrib ) and Manual, NO other
  22.    support-files, fonts or libraries are needed.
  23.  
  24.        Blitt is Copyright of P.Juhasz and is placed into the Public Domain
  25.    for unrestricted use by any individual at his or her own leisure. Any
  26.    possible damage arising from the use or misuse of this program is the
  27.    responsibility of the user. Non-commercial copying or distribution - as
  28.    part of a PD-collection - HAS to include at least this Manual from this
  29.    directory. It is prohibited to copy or distribute Blitt for commercial
  30.    gain, be it on it's own or as part of any other package or application
  31.    without the prior consent of the Author. Any breach of this restriction,
  32.    whether out of ignorance or intentional, will cost the peace of mind of
  33.    the perpetrator - bringing with it BAD karma.
  34.  
  35.  
  36.  
  37.  
  38.  
  39.        Contents of directory:
  40.        ----------------------
  41.  
  42.         Blitt           Blitt.info          -   The program itself
  43.         Manual          Manual.info         -   This text file
  44.         USAScrib        USAScrib.info       -   NTSC Picture for U.S.A.
  45.         Scribble        Scribble.info       -   PAL Picture for the rest
  46.  
  47.  
  48.  
  49.  
  50.  
  51.        The Panel:
  52.        ----------
  53.  
  54.        All the gadgets on the panel should be self-explanatory, so there
  55.    is no need for lengthy explanations. Here is a list as they appear from
  56.    left to right:
  57.  
  58.  
  59.        red ON gadget       - will 'switch off' the program - exit
  60.        Screen resolution   - not implemented
  61.        Disk                - save the screen as a IFF ILBM
  62.        Brush               - define source for blit
  63.        BitMap/Mask         - straight or masked blit
  64.        UNDO                - ah, right...
  65.        BLITT  ©            - some help
  66.        Mask                - more help
  67.        Minterm             - even more help
  68.        Wheels ( 4 )        - these turn the numbers up/down ( 0 to F )
  69.        Black/White         - the screen depth gadget ( one-way only )
  70.  
  71.  
  72.  
  73.  
  74.  
  75.        Usage:
  76.        ------
  77.  
  78.      -Click on `brush' icon        - mouse-pointer will change to `Srce'
  79.      -Define outline on display    - mouse-pointer will change to `Blitt'
  80.      -Set Mask and Minterm         - FF/C0 = straight copy
  81.      -Put the brush anywhere
  82.      -Click on `brush' icon        - mouse-pointer will change back to arrow
  83.  
  84.        Clicking on the `disk' icon opens a requester with a string gadget to
  85.    save the screen in standard IFF ILBM format, compatible with DPaint.
  86.  
  87.    - to get rid of the panel, press RMB at any time ( except requester up )
  88.  
  89.    - on the help-pages RMB will take you back a page, while LMB or
  90.      any key will advance a page
  91.  
  92.  
  93.  
  94.  
  95.  
  96.        Key shortcuts:
  97.        --------------
  98.  
  99.        q   -   quits                   u   -   undo
  100.        p   -   panel up/down           b   -   start/stop brush
  101.        m   -   toggle mask
  102.        h   -   this help page
  103.  
  104.  
  105.  
  106.  
  107.  
  108.        `C' specifics:
  109.        --------------
  110.  
  111.        The syntax of the commands should be available from any good book,
  112.    but here is a quick recap:
  113.  
  114.  
  115.    planecnt = BltBitMap( srcBM,           srcX, srcY, dstBM,
  116.    D0                    A0               D0:16 D1:16 A1
  117.    ULONG    = BltBitMap( struct BitMap *, WORD, WORD, struct BitMap *,
  118.  
  119.               dstX, dstY, sizX, sizY, Minterm, Mask   [, TempA   ] )
  120.               D2:16 D3:16 D4:16 D5:16 D6:8     D7:8   [  A7      ]
  121.               WORD, WORD, WORD, WORD, UBYTE,   UBYTE  [, UWORD * ] )
  122.  
  123.        Most of the parameters are self-explanatory, all coordinates as well
  124.    as width/height are pixel values.
  125.  
  126.        Minterm specifies the way the source is treated as it is copied to
  127.    the destination, whether it is a straight copy ($C0) or whether it is
  128.    logically combined with the destination.
  129.  
  130.        Mask specifies the bitplanes that are to be affected by the copy.
  131.  
  132.        TempA is a temporary buffer for blits where source and destination
  133.    overlap. It can be left out altogether.
  134.  
  135.  
  136.  
  137.  
  138.    void    BltMaskBitMapRastPort( srcBM,           srcX, srcY,
  139.                                   A0               D0    D1
  140.                                 ( struct BitMap *, WORD, WORD,
  141.  
  142.         dstRP,             dstX, dstY, sizX, sizY, minterm, bltmask )
  143.         A1                 D2    D3    D4    D5    D6       A2
  144.         struct RastPort *, WORD, WORD, WORD, WORD, UBYTE,   APTR    )
  145.  
  146.  
  147.        In this case minterm is restricted by software to $e0 if you set
  148.    the dial to >= $a0, otherwise the program uses a minterm value of $20.
  149.  
  150.        The mask used in this operation, pointed to by bltmask, is a single
  151.    bitplane from the display-bitmap - its top left corner defined by
  152.    clicking on the display. This can be easily selected with the right wheel
  153.    of the mask-dial. The Mask will be the same size as the brush that is
  154.    subsequently defined.
  155.  
  156.        Normally the Mask parameter specifies the bitplanes that are affected
  157.    by the blit operation.
  158.  
  159.        In the case of blitting through a mask, whatever value is set, will
  160.    be logically AND`ed with $07 and limited to the number of bitplanes of
  161.    the display to get a single bit-plane to act as the mask.
  162.  
  163.        The mask is selected by clicking on the icon that looks like rows
  164.    of red, green and blue dots and changes to a `mask' when selected.
  165.    The mouse-pointer changes to `Mask' and you can click the top-left
  166.    corner of where your mask is located, after which the mouse-pointer
  167.    changes to the usual `Srce' to let you cut out the brush.
  168.  
  169.  
  170.  
  171.  
  172.  
  173.        Tutorial:
  174.        ---------
  175.  
  176.        To start with, you can either use one of the sample pictures ( PAL
  177.    and NTSC should both be present in this same directory ), or take the
  178.    more individual route, much more artistic...
  179.  
  180.        Load up DPaint or any other grafix tool and write some coloured
  181.    text down the left hand side, each line a different colour and any
  182.    font you like. Into the right hand side, place a part of a picture,
  183.    one of your own brushes or one taken from the public domain.
  184.  
  185.        Once the picture is saved, remember to make sure it's got an icon,
  186.    click on this, hold shift and double-click on the Blitt icon. CLI
  187.    users please shut up - you know what to do. There are no switches etc..
  188.  
  189.        Once Blitt is up, it will display your picture. This, for the time,
  190.    has to be a low resolution ( 320 x 256/200 ) IFF ILBM screen. The panel
  191.    comes up with Mask & Minterm values set for a straight copy.
  192.  
  193.        To start, click on the brush gadget - the mouse-pointer will change
  194.    to `Srce' - and drag the pointer from the top left of the area you want
  195.    to copy (the block of text in this case) to the bottom right. This, on
  196.    releasing LMB, defines the size of the brush. This is limited to ¼-screen
  197.    size if there is insufficient memory, otherwise the entire display can
  198.    be picked up - what would anyone need that for...
  199.  
  200.        Once the source is defined, the mouse-pointer changes to `Blitt'.
  201.    Now we can set up a minterm value - if we have not already done so.
  202.    Respective values for mask/minterm FF/E0 is quite allright for this
  203.    example. After this we can put the brush down on the destination, in
  204.    this case on the picture in the right half of the screen.
  205.  
  206.        If the result is not quite as expected, there is the Undo gadget and
  207.    many possibilities with different mask/minterm values. Blitting through
  208.    a mask can also give interesting results or try to use different types
  209.    of pictures with different colours.
  210.  
  211.  
  212.  
  213.  
  214.  
  215.        Credits:
  216.        --------
  217.  
  218.    Paul Juhasz                 -   Design, Gfx and coding
  219.    Janice Bailey               -   Crash testing and lots of moral support
  220.  
  221.    Special thanks also go to:
  222.    Anders Bjerin               -   the Amiga C Club and Intuition examples
  223.    Robert Muszinsky            -   for the copy-parties ( PD only! )
  224.  
  225.    And the F-19 Crew:
  226.    Baggy Undercarriage         -   "Mavericks! Mavericks!"
  227.    Johnny Ace                  -   "Steady on - flaps down..."
  228.    Hippy Warrior               -   "Sneak up on Pechenga..."
  229.    TROJAN                      -   "How about a game of Golf?"
  230.  
  231.  
  232.  
  233.  
  234.  
  235.        History:
  236.        --------
  237.  
  238.        The original version of Blitt was written for my own convenience, it
  239.    took two weeks using `nasty' low-level graphics, took over the system and
  240.    was about as friendly as a side-winder at close range. It was fast, but
  241.    it only worked for ME, and then only when I was threatening it with
  242.    everything in my tools: directory.
  243.  
  244.        Since there still must be people with less patience than myself, it
  245.    was soon decided that Blitt needs to get civilized to be useful to anyone
  246.    who just wants to click and go. That's why it now uses WorkBench icons,
  247.    the Intuition library, allows any other task to get on with its business,
  248.    doesn't trash or steal memory on exiting and works happily on ECS/V2.0
  249.    or even NTSC systems. The latter I am only hoping it does, since I could
  250.    only test it with the help of my trusty old ½meg A1000, which sometimes
  251.    (mostly after it's been thoroughly confused!) boots up into NTSC.
  252.  
  253.        The brush movement is still far too slow with large brushes, but on
  254.    the other hand, all gadgets are available at any time, including the
  255.    depth-gadget, which will put both display and panel to the back. If a
  256.    brush is active when you need to re-activate Blitt, click on the panel
  257.    first so the brush does not get copied to the display.
  258.  
  259.        Since I think the Amiga is beautiful, I tried to take as much care
  260.    in writing this program as I could, but as humans are quite fallible,
  261.    I would appreciate any feedback on the program's usage, features and
  262.    possibilities.
  263.  
  264.        If you find any bugs or can think of any improvements, please get
  265.    in touch with:
  266.  
  267.  
  268.    P. Juhasz                                 Tel.: 081 677 9425
  269.    28 Ellora Road
  270.    Streatham Common
  271.    London SW16 6JF
  272.  
  273.  
  274.  
  275.  
  276.                                * * * * *
  277.  
  278.  
  279.  
  280.