home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / oct93 / 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.                     of this image buffer into lines of RGB data.  The
  238.                     function will fail if this tag is not given.
  239.  
  240.                 AMI_PutDataCode:
  241.                     (int (*)()) Hook function to store lines of RGB data
  242.                     into this image buffer, converting to its native
  243.                     format as necessary.  The function will fail if this
  244.                     tag is not given.
  245.  
  246.                 AMI_Red:
  247.                     (UBYTE *) Pointer to contiguous block of chunky red
  248.                     image data, if you are able to provide this information.
  249.                     If not specified, an application will be forced to go
  250.                     through a translation process to get to your image data.
  251.  
  252.                 AMI_Green:
  253.                     (UBYTE *) Pointer to contiguous block of chunky green
  254.                     image data, if you are able to provide this information.
  255.  
  256.                 AMI_Blue:
  257.                     (UBYTE *) Pointer to contiguous block of chunky blue
  258.                     image data, if you are able to provide this information.
  259.  
  260.                 AMI_Alpha:
  261.                     (UBYTE *) Pointer to contiguous block of chunky 8-bit
  262.                     alpha channel data, if you are able to provide this
  263.                     information.
  264.  
  265.                 AMI_AspectX:
  266.                     (LONG) Horizontal pixel aspect ratio of the new image.
  267.                     Defaults to 1.
  268.  
  269.                 AMI_AspectY:
  270.                     (LONG) Vertical pixel aspect ratio of the new image.
  271.                     Defaults to 1.
  272.  
  273.                 AMI_DPIX:
  274.                     (LONG) Horizontal pixels per inch of the new image.
  275.                     Defaults to 300.
  276.  
  277.                 AMI_DPIY:
  278.                     (LONG) Vertical pixels per inch of the new image.
  279.                     Defaults to 300.
  280.  
  281.                 AMI_OwnerName:
  282.                     (char *) Provide the name of the application that
  283.                     created this image.  Other applications can use
  284.                     this information.  Defaults to NULL, meaning the
  285.                     owner will remain anonymous.
  286.  
  287.     RESULTS
  288.         image -- pointer to MagicImage structure.
  289.  
  290.     EXAMPLE
  291.  
  292.     NOTES
  293.         The TAG_SKIP and TAG_MORE tags are not supported.
  294.  
  295.     BUGS
  296.  
  297.     SEE ALSO
  298.  
  299.  
  300. magic.library/AttemptLockMagicImage       magic.library/AttemptLockMagicImage
  301.  
  302.     NAME
  303.         AttemptLockMagicImage -- Attempt to obtain a lock on a MAGIC image.
  304.  
  305.     SYNOPSIS
  306.         success = AttemptLockMagicImage ( magicHandle, type );
  307.         D0.L                              A0           D0.L
  308.  
  309.         BOOL AttemptLockMagicImage ( struct MagicHandle *, LONG );
  310.  
  311.     FUNCTION
  312.         Attempt to get a read or write lock on the specified public image.  You
  313.         should always obtain a write lock before attempting to modify a
  314.         public image, so two tasks will not try to modify an image at
  315.         the same time.
  316.  
  317.         If the image is write locked by another task, this function will fail
  318.         immediately.  Use LockMagicImage() if you want to wait for the image
  319.         to become available.
  320.  
  321.     INPUTS
  322.         magicHandle -- pointer to a valid image handle as obtained from
  323.             OpenPublicImageA().
  324.  
  325.         type -- type of lock to obtain, LMI_Read or LMI_Write.
  326.  
  327.     RESULTS
  328.         success -- TRUE if the lock was obtained, FALSE on failure.
  329.  
  330.     EXAMPLE
  331.  
  332.     NOTES
  333.  
  334.     BUGS
  335.  
  336.     SEE ALSO
  337.  
  338.  
  339. magic.library/CloseMagicImage                   magic.library/CloseMagicImage
  340.  
  341.     NAME
  342.         CloseMagicImage -- Close a public MAGIC image.
  343.  
  344.     SYNOPSIS
  345.         success = CloseMagicImage ( magicHandle );
  346.         D0.L                        A0
  347.  
  348.         BOOL CloseMagicImage ( struct MagicImage * );
  349.  
  350.     FUNCTION
  351.         Close a previously opened public image, freeing it to be removed
  352.         by its owner.
  353.  
  354.     INPUTS
  355.         magicHandle -- pointer to a valid image handle as obtained from
  356.             OpenMagicImageA().
  357.  
  358.     RESULTS
  359.         success -- TRUE if successful, FALSE on failure.
  360.  
  361.     EXAMPLE
  362.  
  363.     NOTES
  364.  
  365.     BUGS
  366.  
  367.     SEE ALSO
  368.  
  369.  
  370.  
  371. magic.library/CycleMagicImage                   magic.library/CycleMagicImage
  372.  
  373.     NAME
  374.         CycleMagicImage -- Cycle to next application using a MAGIC image.
  375.  
  376.     SYNOPSIS
  377.         CycleMagicImage ( magicHandle );
  378.                           A0
  379.  
  380.         void CycleMagicImage ( struct MagicHandle * );
  381.  
  382.     FUNCTION
  383.         Bring the interface of the next application that has access to the
  384.         given image to the front.  This can be used as a convenience to the
  385.         user when switching between applications.
  386.  
  387.         This function is asynchronous, meaning it returns immediately.
  388.  
  389.         This works by sending a MMSG_TOFRONT message to the next application
  390.         in line that has opened the image.
  391.  
  392.     INPUTS
  393.         magicHandle -- pointer to a valid image handle as obtained from
  394.             OpenMagicImageA().
  395.  
  396.     RESULTS
  397.         None.
  398.  
  399.     EXAMPLE
  400.  
  401.     NOTES
  402.  
  403.     BUGS
  404.  
  405.     SEE ALSO
  406.  
  407.  
  408. magic.library/FreeMagicImage                     magic.library/FreeMagicImage
  409.  
  410.     NAME
  411.         FreeMagicImage -- Free a MAGIC image structure.
  412.  
  413.     SYNOPSIS
  414.         FreeMagicImage ( magicImage );
  415.                          A0
  416.  
  417.         void FreeMagicImage ( struct MagicImage * );
  418.  
  419.     FUNCTION
  420.         Frees all memory associated with a MagicImage structure.  This call
  421.         must only be used on MagicImage's created with the AllocMagicImageA()
  422.         function.
  423.  
  424.     INPUTS
  425.         magicImage -- pointer to a MagicImage structure to free.
  426.  
  427.     RESULTS
  428.         None.
  429.  
  430.     EXAMPLE
  431.  
  432.     NOTES
  433.         This function does not check to see if anyone has opened the image in
  434.         question; only the owner of an image should free the associated
  435.         MagicImage structure when everyone has closed it.
  436.  
  437.     BUGS
  438.  
  439.     SEE ALSO
  440.  
  441.  
  442. magic.library/GetMagicImageDataA             magic.library/GetMagicImageDataA
  443.  
  444.     NAME
  445.         GetMagicImageDataA -- Retreive rows of image data.
  446.         GetMagicImageData -- varargs stub to GetMagicImageDataA.
  447.  
  448.     SYNOPSIS
  449.         success = GetMagicImageDataA ( magicHandle, yoffset, rows, tagList );
  450.         D0.L                           A0           D0.L     D1.L  A1
  451.  
  452.         BOOL GetMagicImageDataA ( struct MagicHandle *, LONG, LONG,
  453.                                   struct TagItem * );
  454.  
  455.         success = GetMagicImageData ( magicHandle, yoffset, rows, ... );
  456.  
  457.         BOOL GetMagicImageData ( struct MagicHandle *, LONG, LONG, ... );
  458.  
  459.     FUNCTION
  460.         Copies image data from the given MAGIC image into caller-supplied
  461.         buffers, calling the image's translation function (set by the owner of
  462.         the image).
  463.  
  464.     INPUTS
  465.         magicHandle -- pointer to a valid image handle as obtained from
  466.             OpenPublicImageA().
  467.  
  468.         yoffset -- topmost row to start copying from, starting from 0.
  469.  
  470.         rows -- number of rows of image data to copy.
  471.  
  472.         tagList -- tags describing the image data to get:
  473.  
  474.                 GMI_Red:
  475.                     (UBYTE *) Copies red image data into the caller's buffer,
  476.                     1 byte per pixel.  If the image buffer is greyscale, the
  477.                     greyscale data will be copied.
  478.  
  479.                 GMI_Green:
  480.                     (UBYTE *) Copies green image data into the caller's
  481.                     buffer, 1 byte per pixel.
  482.  
  483.                 GMI_Blue:
  484.                     (UBYTE *) Copies blue image data into the caller's buffer,
  485.                     1 byte per pixel.
  486.  
  487.                 GMI_RGB:
  488.                     (UBYTE *) Copies RGB imgae data into the caller's buffer,
  489.                     3 bytes per pixel in the format RGBRGBRGB...
  490.  
  491.                 GMI_ARGB:
  492.                     (UBYTE *) Copies RGB image data + alpha channel
  493.                     information into the caller's buffer, 4 bytes per pixel in
  494.                     the format ARGBARGBARGB...
  495.  
  496.                 GMI_Alpha:
  497.                     (UBYTE *) Copies alpha channel information into the
  498.                     caller's buffer, 1 byte per pixel.
  499.  
  500.     RESULTS
  501.         success -- TRUE if all data was succesfully copied, or FALSE if
  502.             something failed.
  503.  
  504.     EXAMPLE
  505.  
  506.     NOTES
  507.         You should always obtain a read lock before reading image data!
  508.  
  509.     BUGS
  510.  
  511.     SEE ALSO
  512.  
  513.  
  514. magic.library/IsMagicMessage                     magic.library/IsMagicMessage
  515.  
  516.     NAME
  517.         IsMagicMessage -- Validate a MagicMessage.
  518.  
  519.     SYNOPSIS
  520.         success = IsMagicMessage ( message );
  521.         D0.L                       A0
  522.  
  523.         BOOL IsMagicMessage ( struct Message * );
  524.  
  525.     FUNCTION
  526.         Check to see if the given message structure is actually a
  527.         MagicMessage.  This may be used when you are receiving several message
  528.         types from different sources at the same message port.
  529.  
  530.     INPUTS
  531.         message -- pointer to a Message to check.
  532.  
  533.     RESULTS
  534.         success -- TRUE if the message is a MagicMessage, FALSE if it is not.
  535.  
  536.     EXAMPLE
  537.  
  538.     NOTES
  539.  
  540.     BUGS
  541.  
  542.     SEE ALSO
  543.  
  544.  
  545. magic.library/LockMagicImage                     magic.library/LockMagicImage
  546.  
  547.     NAME
  548.         LockMagicImage -- Obtain a lock on a public MAGIC image.
  549.  
  550.     SYNOPSIS
  551.         success = LockMagicImage ( magicHandle, type );
  552.         D0.L                       A0           D0.L
  553.  
  554.         BOOL LockMagicImage ( struct MagicHandle *, LONG );
  555.  
  556.     FUNCTION
  557.         Obtain a read or write lock on the specified public image.  You should
  558.         always get a write lock before attempting to modify a public, so that
  559.         two tasks will not try to modify an image at the same time.  It is also
  560.         important to obtain a read lock before examining image data.
  561.  
  562.         If the specified image is not available to be locked, this function will
  563.         wait until it becomes available.
  564.  
  565.     INPUTS
  566.         magicHandle -- pointer to a valid image handle as obtained from
  567.             OpenPublicImageA().
  568.  
  569.         type -- type of lock to obtain, LMI_Read or LMI_Write.
  570.  
  571.     RESULTS
  572.         success -- TRUE if the lock was obtained, or FALSE on failure.  The
  573.             function can only fail by supplying an invalid lock type.
  574.  
  575.     EXAMPLE
  576.  
  577.     NOTES
  578.  
  579.     BUGS
  580.  
  581.     SEE ALSO
  582.  
  583.  
  584. magic.library/OpenMagicImageA                   magic.library/OpenMagicImageA
  585.  
  586.     NAME
  587.         OpenMagicImageA -- Obtain access to a public MAGIC image.
  588.         OpenMagicImage -- varargs stub to OpenMagicImageA().
  589.  
  590.     SYNOPSIS
  591.         magicHandle = OpenMagicImageA ( magicImage, name, tagList );
  592.         D0.L                            A0          A1    A2
  593.  
  594.         struct MagicHandle *OpenMagicImageA ( struct MagicImage *,
  595.                                               char *, struct TagItem * );
  596.  
  597.         magicHandle = OpenMagicImage ( magicImage, name, ... );
  598.  
  599.         struct MagicHandle *OpenMagicImage ( struct MagicImage *,
  600.                                              char *, ... );
  601.  
  602.     FUNCTION
  603.         Attempt to open a public image for use by an application.  Once the
  604.         image is opened, an application may access the image data either
  605.         directly or through translation functions (the application should make
  606.         sure to obtain an appropriate lock before accessing/modifying the
  607.         image data).  The image handle returned is used in many other
  608.         magic.library functions.
  609.  
  610.     INPUTS
  611.         magicImage -- pointer to the MagicImage structure you want to open for
  612.             your use.  If NULL, then the name parameter is used to determine
  613.             the public image you want to open.
  614.  
  615.         name -- pointer to (case sensitive) NUL-terminated name of the public
  616.             image you want to open.  If both the magicImage and name
  617.             parameters are NULL, then the default (or active) public image
  618.             will be returned.
  619.  
  620.         tagList -- tags used in opening the image:
  621.  
  622.                 OMI_MsgPort:
  623.                     (struct MsgPort *) Pointer to a message port which the
  624.                     MagicServer program will use to send you messages
  625.                     concerning this image (such as when to redraw, etc.).
  626.  
  627.                 OMI_OwnerPort:
  628.                     (struct MsgPort *) Only the owner of an image should use
  629.                     this tag.  It is identical to OMI_MsgPort, but when the
  630.                     owner of an image opens it (as it must do like anyone
  631.                     else), it should use this tag instead.
  632.  
  633.     RESULTS
  634.         magicHandle -- image handle used by other magic.library functions, or
  635.             NULL if the image could not be opened for some reason.
  636.  
  637.     EXAMPLE
  638.  
  639.     NOTES
  640.         Note that the owner of an image must also open it (ie. use
  641.         OpenMagicImage after calling AddMagicImage).  This is so the owner
  642.         will receive the same messages everyone else will.
  643.  
  644.     BUGS
  645.  
  646.     SEE ALSO
  647.  
  648.  
  649. magic.library/PickMagicImageA                   magic.library/PickMagicImageA
  650.  
  651.     NAME
  652.         PickMagicImageA -- Select MAGIC image from requester.
  653.         PickMagicImage -- varargs stub to PickMagicImageA.
  654.  
  655.     SYNOPSIS
  656.         magicImage = PickMagicImageA ( screen, tagList );
  657.         D0.L                           A0      A1
  658.  
  659.         struct MagicImage *PickMagicImageA ( struct Screen *,
  660.                                              struct TagItem * );
  661.  
  662.         magicImage = PickMagicImage ( screen, firstTag, ... );
  663.  
  664.         struct MagicImage *PickMagicImage ( struct Screen *, ... );
  665.  
  666.     FUNCTION
  667.         Open a standard requester on the caller's choice of
  668.         screen to allow the user to choose a MAGIC image.
  669.         In the default case, all currently available MAGIC images
  670.         will be shown, but tags may be specified to filter out
  671.         certain images.
  672.  
  673.     INPUTS
  674.         screen -- Screen on which to open, or NULL to open on the default
  675.             public screen (ie. Workbench).  Note that the screen will be
  676.             shifted up to make room for the requester if necessary.
  677.  
  678.         tagList -- Tags controlling the image list:
  679.  
  680.                 PMI_MinWidth:
  681.                     (LONG) Only show images whose width is at least this
  682.                     value.
  683.  
  684.                 PMI_MinHeight:
  685.                     (LONG) Only show images whose height (in pixels) is at
  686.                     least this value.
  687.  
  688.                 PMI_MinDepth:
  689.                     (LONG) Only show images whose depth (in byte planes) is at
  690.                     least this value.  Can be used to filter out 8-bit
  691.                     greyscale images.
  692.  
  693.                 PMI_MaxWidth:
  694.                     (LONG) Only show images whose width (in pixels) is less
  695.                     than this value.
  696.  
  697.                 PMI_MaxHeight:
  698.                     (LONG) Only show images whose height (in pixels) is less
  699.                     than this value.
  700.  
  701.                 PMI_MaxDepth:
  702.                     (LONG) Only show images whose depth (in byte planes) is
  703.                     less than this value.  Can be used to filter out color
  704.                     images.
  705.  
  706.                 PMI_ShowSize:
  707.                     (BOOL) If TRUE, display the sizes of images along with
  708.                     their names.
  709.  
  710.                 PMI_ShowOwner :
  711.                     (BOOL) If TRUE, display the owner of images along with
  712.                     their names.
  713.  
  714.                 PMI_All :
  715.                     (BOOL) If TRUE, show all available images without
  716.                     filtering.
  717.  
  718.                 PMI_ExcludeOwner:
  719.                     (char *) Exclude all images that were created by the given
  720.                     owner.  This can be used to filter out images created by
  721.                     the caller.
  722.  
  723.     RESULTS
  724.         magicImage -- Pointer to MagicImage selected by the user, or NULL if
  725.             the user cancels the operation.  The image must still be opened
  726.             before it can be used.
  727.  
  728.     EXAMPLE
  729.  
  730.     NOTES
  731.         The TAG_SKIP and TAG_MORE tags are not supported.
  732.         This function requires GadTools V37+.
  733.  
  734.     BUGS
  735.  
  736.     SEE ALSO
  737.  
  738.  
  739. magic.library/PutMagicImageDataA             magic.library/PutMagicImageDataA
  740.  
  741.     NAME
  742.         PutMagicImageDataA -- Write pixel data into a public MAGIC image.
  743.         PutMagicImageData -- varargs stub to PutMagicImageDataA.
  744.  
  745.     SYNOPSIS
  746.         success = PutMagicImageDataA ( magicHandle, yoffset, rows, tagList );
  747.         D0.L                           A0           D0.L     D1.L  A1
  748.  
  749.         BOOL PutMagicImageDataA ( struct MagicHandle *, LONG, LONG,
  750.                                   struct TagItem * );
  751.  
  752.         success = PutMagicImageData ( magicHandle, yoffset, rows, ... );
  753.  
  754.         BOOL PutMagicImageData ( struct MagicHandle *, LONG, LONG, ... );
  755.  
  756.     FUNCTION
  757.         Copies image data from the caller-supplied buffers into the given
  758.         MAGIC image, calling the image's translation function (set by the
  759.         owner of the image).
  760.  
  761.     INPUTS
  762.         magicHandle -- pointer to a valid image handle as obtained from
  763.             OpenPublicImageA().
  764.  
  765.         yoffset -- topmost row to start copying from, starting from 0.
  766.  
  767.         rows -- number of rows of image data to copy.
  768.  
  769.         tagList -- tags describing the image data to get:
  770.  
  771.                 GMI_Red:
  772.                     (UBYTE *) Stores red image data, as supplied in the
  773.                     caller's buffer, 1 byte per pixel.
  774.  
  775.                 GMI_Green:
  776.                     (UBYTE *) Stores green image data, as supplied in the
  777.                     caller's buffer, 1 byte per pixel.
  778.  
  779.                 GMI_Blue:
  780.                     (UBYTE *) Stores blue image data as supplied in the
  781.                     caller's buffer, 1 byte per pixel.
  782.  
  783.                 GMI_RGB:
  784.                     (UBYTE *) Stores RGB image data as supplied in the
  785.                     caller's buffer, 3 bytes per pixel in the format
  786.                     RGBRGBRGB...
  787.  
  788.                 GMI_ARGB:
  789.                     (UBYTE *) Stores RGB image data + alpha channel
  790.                     information as supplied in the caller's buffer,
  791.                     4 bytes per pixel in the format ARGBARGBARGB...
  792.  
  793.                 GMI_Alpha:
  794.                     (UBYTE *) Stores alpha channel information as supplied in
  795.                     the caller's buffer, 1 byte per pixel.
  796.  
  797.     RESULTS
  798.         success -- TRUE if all data was succesfully copied, or FALSE if
  799.             something failed.
  800.  
  801.     EXAMPLE
  802.  
  803.     NOTES
  804.         You should always obtain a write lock before writing image data!
  805.  
  806.     BUGS
  807.  
  808.     SEE ALSO
  809.  
  810.  
  811. magic.library/RedrawMagicImage                 magic.library/RedrawMagicImage
  812.  
  813.     NAME
  814.         RedrawMagicImage -- Refresh display of MAGIC image.
  815.  
  816.     SYNOPSIS
  817.         RedrawMagicImage ( magicHandle, left, top, width, height );
  818.                            A0           D0.L  D1.L D2.L   D3.L
  819.  
  820.         void RedrawMagicImage (struct MagicHandle *, LONG, LONG, LONG, LONG);
  821.  
  822.     FUNCTION
  823.         Signal all the openers of the given image to refresh their displays of
  824.         the image.  All openers are signalled EXCEPT THE ONE THAT CALLED THIS
  825.         FUNCTION!
  826.  
  827.         This function is asynchronous, meaning it returns immediately.
  828.  
  829.         This works by sending a MMSG_REDRAW to all tasks that have opened this
  830.         image, except the task calling this function.
  831.  
  832.     INPUTS
  833.         magicHandle -- pointer to a valid image handle as obtained from
  834.             OpenMagicImageA().
  835.  
  836.         left, top -- upper left corner of area to redraw, starting from 0,0 in
  837.             the far upper left of the image.
  838.  
  839.         width, height -- size of the area to redraw, in pixels.
  840.  
  841.     RESULTS
  842.         None.
  843.  
  844.     EXAMPLE
  845.  
  846.     NOTES
  847.         Due to possible bottlenecks when redrawing several displays at once,
  848.         an application should lower its priority when redrawing due to a
  849.         MMSG_REDRAW message.
  850.  
  851.     BUGS
  852.  
  853.     SEE ALSO
  854.  
  855.  
  856. magic.library/RemMagicImage                       magic.library/RemMagicImage
  857.  
  858.     NAME
  859.         RemMagicImage -- Remove MAGIC image from public scrutiny.
  860.  
  861.     SYNOPSIS
  862.         success = RemMagicImage ( magicImage );
  863.         D0.L                      A0
  864.  
  865.         BOOL RemMagicImage ( struct MagicImage * );
  866.  
  867.     FUNCTION
  868.         Remove the given MagicImage from the public list of images.  Only the
  869.         owner of an image should use this function.  Once the image is removed
  870.         it may be freed at will.
  871.  
  872.         If other applications still have a handle on this image (ie. they have
  873.         opened it), the magic server will send a MMSG_CLOSE to all the
  874.         applications that have it open so they will release the image.
  875.  
  876.     INPUTS
  877.         magicImage -- pointer to a MagicImage structure to be removed.
  878.  
  879.     RESULTS
  880.         success -- TRUE if the image was removed, or FALSE if the image could
  881.             not be removed for some reason.
  882.  
  883.     EXAMPLE
  884.  
  885.     NOTES
  886.         The owner of an image *MUST* close the image BEFORE calling
  887.         RemMagicImage or a deadlock will occur.
  888.  
  889.     BUGS
  890.  
  891.     SEE ALSO
  892.  
  893.  
  894. magic.library/RestoreMagicImage               magic.library/RestoreMagicImage
  895.  
  896.     NAME
  897.         RestoreMagicImage -- Request owner to restore undo copy of image.
  898.  
  899.     SYNOPSIS
  900.         success = RestoreMagicImage ( magicHandle );
  901.         D0.L                          A0
  902.  
  903.         BOOL RestoreMagicImage ( struct MagicHandle * );
  904.  
  905.     FUNCTION
  906.         Send a request to the owner of a MAGIC image to restore the latest
  907.         undo copy into the image.
  908.  
  909.         The function does not return until the restoration is complete.
  910.  
  911.         This works by sending a MMSG_RESTOREUNDO message to the owner of the
  912.         image.
  913.  
  914.     INPUTS
  915.         magicHandle -- pointer to a valid image handle as obtained from
  916.             OpenMagicImageA().
  917.  
  918.     RESULTS
  919.         success -- TRUE if the copy was successfully restored, or FALSE if
  920.             something went wrong.
  921.  
  922.     EXAMPLE
  923.  
  924.     NOTES
  925.         The owner of an image may choose to ignore the request.
  926.  
  927.         The owner of an image should never call this function, or a deadlock
  928.         will occur.
  929.  
  930.     BUGS
  931.  
  932.     SEE ALSO
  933.  
  934.  
  935. magic.library/SaveMagicImage                     magic.library/SaveMagicImage
  936.  
  937.     NAME
  938.         SaveMagicImage -- Request owner to save an undo copy of image.
  939.  
  940.     SYNOPSIS
  941.         success = SaveMagicImage ( magicHandle, left, top, width, height );
  942.         D0.L                       A0           D0.L  D1.L D2.L   D3.L
  943.  
  944.         BOOL SaveMagicImage ( struct MagicHandle *, LONG, LONG, LONG, LONG );
  945.  
  946.     FUNCTION
  947.         Request the owner of the given MAGIC image to store a copy of the area
  948.         indicated in a temporary "undo" buffer which may be restored later.
  949.         The owner of an image is responsible for making and restoring undo
  950.         copies.
  951.  
  952.         This function does not return until the save is complete.
  953.  
  954.         This works by sending an MMSG_SAVEUNDO message to the owner of an
  955.         image and waiting for a reply.
  956.  
  957.     INPUTS
  958.         magicHandle -- pointer to a valid image handle as obtained from
  959.             OpenMagicImageA().
  960.  
  961.         left, top -- upper left corner of area to save, starting from 0,0 in
  962.             the far upper left of the image.
  963.  
  964.         width, height -- size of the area to save, in pixels.
  965.  
  966.     RESULTS
  967.         success -- TRUE if the undo copy was successfully saved, or FALSE if
  968.             it was not.
  969.  
  970.     EXAMPLE
  971.  
  972.     NOTES
  973.         The owner of an image may choose to ignore the request, or save the
  974.         full area of an image instead of the requested subset.
  975.  
  976.         The owner of an image should never call this function, or a deadlock
  977.         will occur.
  978.  
  979.     BUGS
  980.  
  981.     SEE ALSO
  982.  
  983.  
  984. magic.library/SetDefaultMagicImage         magic.library/SetDefaultMagicImage
  985.  
  986.     NAME
  987.         SetDefaultMagicImage -- Select the "default" MAGIC image.
  988.  
  989.     SYNOPSIS
  990.         success = SetDefaultMagicImage ( magicImage );
  991.         D0.L                             A0
  992.  
  993.         BOOL SetDefaultMagicImage ( struct MagicImage * );
  994.  
  995.     FUNCTION
  996.         Set the "default" image that will be opened when no parameters are
  997.         given to OpenMagicImageA().  This function is reserved for "MAGIC
  998.         image manager" type programs, and shouldn't be used arbitrarily.
  999.  
  1000.     INPUTS
  1001.         magicImage -- pointer to a MagicImage structure as returned by
  1002.             AllocMagicImageA() or obtained through the MagicBase list.
  1003.  
  1004.     RESULTS
  1005.         success -- TRUE if the image was successfully set, or FALSE on
  1006.             failure.
  1007.  
  1008.     EXAMPLE
  1009.  
  1010.     NOTES
  1011.  
  1012.     BUGS
  1013.  
  1014.     SEE ALSO
  1015.  
  1016.  
  1017. magic.library/UnlockMagicImage                 magic.library/UnlockMagicImage
  1018.  
  1019.     NAME
  1020.         UnlockMagicImage -- Release a lock on a public MAGIC image.
  1021.  
  1022.     SYNOPSIS
  1023.         UnlockMagicImage ( magicHandle );
  1024.                            A0
  1025.  
  1026.         void UnlockMagicImage ( struct MagicHandle * );
  1027.  
  1028.     FUNCTION
  1029.         Releases either a read or write lock that you have previously obtained
  1030.         on an image.  The image is then free to be used by others or removed.
  1031.  
  1032.     INPUTS
  1033.         magicHandle -- pointer to a valid image handle as obtained from
  1034.             OpenPublicImageA().
  1035.  
  1036.     RESULTS
  1037.         None.
  1038.  
  1039.     EXAMPLE
  1040.  
  1041.     NOTES
  1042.  
  1043.     BUGS
  1044.  
  1045.     SEE ALSO
  1046.  
  1047.  
  1048. magic.library/UpdateMagicImage                 magic.library/UpdateMagicImage
  1049.  
  1050.     NAME
  1051.         UpdateMagicImage -- Signal image openers of size change.
  1052.  
  1053.     SYNOPSIS
  1054.         UpdateMagicImage ( magicHandle );
  1055.                            A0
  1056.  
  1057.         void UpdateMagicImage ( struct MagicHandle * );
  1058.  
  1059.     FUNCTION
  1060.         Signal all openers of an image that the owner has changed the physical
  1061.         dimensions of the image (eg. width, height, depth).  Only the owner of
  1062.         an image may (safely) change the physical dimensions.
  1063.  
  1064.         This function does not return until all openers have updated.
  1065.  
  1066.         This works by sending a MMSG_UPDATE to all openers of the image
  1067.         (except the one calling this function!).
  1068.  
  1069.     INPUTS
  1070.         magicHandle -- pointer to a valid image handle as obtained from
  1071.             OpenMagicImageA().
  1072.  
  1073.     RESULTS
  1074.         None.
  1075.  
  1076.     EXAMPLE
  1077.  
  1078.     NOTES
  1079.  
  1080.     BUGS
  1081.  
  1082.     SEE ALSO
  1083.  
  1084.  
  1085. magic.library/zzzzz
  1086.