home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 1 / FFMCD01.bin / bbs / develop / magic.lha / MAGIC / doc / magic.autodoc
Text File  |  1993-06-24  |  34KB  |  1,086 lines
  1. TABLE OF CONTENTS
  2.  
  3. magic.library/--background--
  4. magic.library/--messages--
  5. magic.library/AddMagicImage
  6. magic.library/AllocMagicImageA
  7. magic.library/AttemptLockMagicImage
  8. magic.library/CloseMagicImage
  9. magic.library/CycleMagicImage
  10. magic.library/FreeMagicImage
  11. magic.library/GetMagicImageDataA
  12. magic.library/IsMagicMessage
  13. magic.library/LockMagicImage
  14. magic.library/OpenMagicImageA
  15. magic.library/PickMagicImageA
  16. magic.library/PutMagicImageDataA
  17. magic.library/RedrawMagicImage
  18. magic.library/RemMagicImage
  19. magic.library/RestoreMagicImage
  20. magic.library/SaveMagicImage
  21. magic.library/SetDefaultMagicImage
  22. magic.library/UnlockMagicImage
  23. magic.library/UpdateMagicImage
  24. magic.library/zzzzz
  25.  
  26.  
  27.  
  28. magic.library/--background--                     magic.library/--background--
  29.  
  30.     - What is MAGIC?
  31.  
  32.     MAGIC is a purely marketing-inspired name for a system of sharing 24-bit
  33.     image data between MAGIC-aware applications.
  34.  
  35.     - Why is this needed?
  36.  
  37.     The primary reason is to make things easier on the user.  It is very
  38.     awkward to have to save an image out of one program, then run a different
  39.     program and then re-load the image to work on it again.  MAGIC allows the
  40.     image data to be "shared" between the two applications _while they are
  41.     running_.
  42.  
  43.     - What's wrong with the clipboard or HotLinks?
  44.  
  45.     MAGIC is specifically oriented towards 24-bit image data (although it is
  46.     certainly extensible to other types of data, but that is beyond the scope
  47.     of this document).  MAGIC is also an "in-memory" system, where the image
  48.     data is kept in memory instead of on disk.  MAGIC is also very transparent
  49.     to the user; there is no need to "publish" or "subscribe".
  50.  
  51.     - How's it work?
  52.  
  53.     The first step is to run a server program that can be run in the
  54.     background to manage MAGIC images and provide a convenient function
  55.     library.  This server program can be placed in a user's WBStartup
  56.     drawer (if they're running 1.3, user's deserve the associated hassles).
  57.  
  58.     When an application wishes to make an image "public" (available to other
  59.     MAGIC-aware applications), he opens the server-created library (called
  60.     "magic.library") and goes through the steps of creating a MAGIC image.
  61.     The image is then added to the public image list and may from then on be
  62.     "opened" by any other application.
  63.  
  64.     The application that creates a MAGIC image and makes it public is known
  65.     throughout this document as the "owner" of an image.  Those applications
  66.     that open a MAGIC image for use are known as "openers" (creative, huh? :).
  67.  
  68.     - How about all those different image data organizations?
  69.  
  70.     This was a major obstacle in the MAGIC system; everyone seems to have a
  71.     different way of storing image data (there's nothing wrong with this, it
  72.     just makes sharing data a little tough).  MAGIC overcomes this like this:
  73.  
  74.     The owner of an image determines the image data organization (the "native"
  75.     organization).  Since the openers may be expecting a different
  76.     organization, translation functions are provided which allow the opener to
  77.     translate the image data into a known format.  This incurs a bit of a
  78.     speed penalty when processing the image, but this seemed the most logical
  79.     way of approaching the problem.
  80.  
  81.     If the owner of an image is using seperate contiguous blocks for the RGB
  82.     data, it may optionally provide this information so that other
  83.     applications that can handle this organization may use the pointers
  84.     directly.  This seems to be the most popular image data organization, and
  85.     is currently in use by several Amiga products.
  86.  
  87.     - Is it easy to support?
  88.  
  89.     One of the goals was to make the task of integrating MAGIC into existing
  90.     applications fairly painless.  True, some work will be required, but we
  91.     think the benefits are well worth it.
  92.  
  93.     - Does MAGIC cost anything?
  94.  
  95.     No.  The server program and documentation for creating MAGIC-aware
  96.     applications will be freely distributable.
  97.  
  98.     - Are there any gotchas?
  99.  
  100.     Your application must be able to support multi-tasking access to
  101.     your image data, because more than one application may be updating
  102.     their displays based on your image data.  In most cases where the
  103.     image data is stored in memory, this will not be a problem.
  104.  
  105.     - Well, you convinced me.  I'll start supporting it right away!
  106.  
  107.     Cool beans. :)
  108.  
  109.     - Is there anything else I should know?
  110.  
  111.     Yeah, too many questions can get on a person's nerves.
  112.  
  113.     - Sorry.
  114.  
  115.     No problem.
  116.  
  117.  
  118. magic.library/--messages--                         magic.library/--messages--
  119.  
  120.     The following types of messages may be sent to your application
  121.     from MAGIC:
  122.  
  123.         MMSG_CLOSE
  124.  
  125.             This is a request for you to close your handle on a
  126.             particular MAGIC image, as someone else is trying to
  127.             release the image.
  128.  
  129.         MMSG_TOFRONT
  130.  
  131.             This is a request to bring your application's interface
  132.             to the front and activate it.
  133.  
  134.         MMSG_REDRAW
  135.  
  136.             This is a request to redraw some or all of a MAGIC
  137.             image's display.
  138.  
  139.         MMSG_UPDATE
  140.  
  141.             This is sent when the physical dimensions of a MAGIC
  142.             image are being changed.  (NOTE:  This version of MAGIC
  143.             does not yet handle physically changing the size of images
  144.             very well.)
  145.  
  146.         MMSG_SAVEUNDO
  147.  
  148.             Request the owner of a MAGIC image to save a copy of some
  149.             or all of the image in an "undo" buffer, presumably before
  150.             some action is done to the image.
  151.  
  152.         MMSG_RESTOREUNDO
  153.  
  154.             Request the owner of a MAGIC image to undo the last changes
  155.             to a MAGIC image.
  156.  
  157.  
  158. magic.library/AddMagicImage                       magic.library/AddMagicImage
  159.  
  160.     NAME
  161.         AddMagicImage -- Make a MAGIC image available to other tasks.
  162.  
  163.     SYNOPSIS
  164.         success = AddMagicImage ( image );
  165.         D0.L                      A0
  166.  
  167.         BOOL AddMagicImage ( struct MagicImage * );
  168.  
  169.     FUNCTION
  170.         Make a previously allocated and initialized MagicImage structure
  171.         available for other applications to open and access.  Only the
  172.         owner of an image should make it public.
  173.  
  174.     INPUTS
  175.         image -- a pointer to an initialized MagicImage structure,
  176.             which should only be allocated with the AllocMagicImageA()
  177.             function.
  178.  
  179.     RESULTS
  180.         success -- TRUE if the image was successfully added, or FALSE on
  181.             failure.
  182.  
  183.     EXAMPLE
  184.  
  185.     NOTES
  186.  
  187.     BUGS
  188.  
  189.     SEE ALSO
  190.  
  191.  
  192. magic.library/AllocMagicImageA                 magic.library/AllocMagicImageA
  193.  
  194.     NAME
  195.         AllocMagicImageA -- Allocate and initialize a MagicImage structure.
  196.         AllocMagicImage -- varargs stub for AllocMagicImageA().
  197.  
  198.     SYNOPSIS
  199.         image = AllocMagicImageA ( taglist );
  200.         D0.L                       A0
  201.  
  202.         struct MagicImage *AllocMagicImageA ( struct TagItem * );
  203.  
  204.         image = AllocMagicImage ( firstTag, ... );
  205.  
  206.         struct MagicImage *AllocMagicImage ( Tag, ... );
  207.  
  208.     FUNCTION
  209.         Allocate and initialize a new MagicImage structure.  You *must*
  210.         use this function to create the structure to be upwardly compatible.
  211.  
  212.     INPUTS
  213.         taglist -- tags used to initialize the PublicImage structure.
  214.  
  215.                 AMI_Width:
  216.                     (LONG) Width of image data in pixels.
  217.  
  218.                 AMI_Height:
  219.                     (LONG) Height of image data in pixels.
  220.  
  221.                 AMI_Depth:
  222.                     (LONG) Depth of image data in 8-bit planes (eg. 1 for an
  223.                     8-bit greyscale image or 3 for a 24-bit RGB color
  224.                     image).
  225.  
  226.                 AMI_Name:
  227.                     (char *) Name of the public image buffer.  Defaults to a
  228.                     unique name.
  229.  
  230.                 AMI_ImageData:
  231.                     (APTR) Information need by the owner of this image to
  232.                     decipher it's contents.  Could be nothing more than a
  233.                     pointer to an array of RGB plane pointers.
  234.  
  235.                 AMI_GetDataCode:
  236.                     (int (*)()) Hook function to convert the native format
  237.