home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / GFX / Converter / MPIMAGE51.LZX / docs / MPImage.doc
Encoding:
Text File  |  1996-10-10  |  10.7 KB  |  350 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. MPImage.library/FreeMPImage
  6. MPImage.library/LoadMPImage
  7. MPImage.library/MPImageErrorMessage
  8. MPImage.library/MPPlanarToChunky
  9. MPImage.library/RescaleMPImage
  10. MPImage.library/SaveMPImageA
  11. MPImage.library/SetMPImageScreen
  12.  
  13.  
  14. MPImage.library/FreeMPImage                        MPImage.library/FreeMPImage
  15.  
  16.    NAME   
  17.   FreeMPImage -- Free an image loaded using LoadMPImage() (V3)
  18.  
  19.    SYNOPSIS
  20.   FreeMPImage( MPi )
  21.                A0
  22.  
  23.   void FreeMPImage( struct MPImage * );
  24.  
  25.    FUNCTION
  26.   Frees all data associated loaded with an image using LoadMPImage().
  27.  
  28.    INPUTS
  29.   MPi - structure returned by LoadMPImage().
  30.  
  31.    RESULT
  32.   None.
  33.  
  34.    EXAMPLE
  35.  
  36.    NOTES
  37.  
  38.    BUGS
  39.  
  40.    SEE ALSO
  41.   LoadMPImage()
  42.  
  43. MPImage.library/LoadMPImage                        MPImage.library/LoadMPImage
  44.  
  45.    NAME   
  46.   LoadMPImage -- Load an image in various formats (V4)
  47.  
  48.    SYNOPSIS
  49.   MPi = LoadMPImage( filename,screen,Flags )
  50.   D0                       A0       A1     D0
  51.  
  52.   struct MPImage *LoadMPImage
  53.                   ( const char *,struct Screen *,ULONG);
  54.  
  55.    FUNCTION
  56.   Load an image in BitMap, EGSBitMap or RGB format.
  57.  
  58.    INPUTS
  59.   filename - name of file from which to load image
  60.            - -c or -cnumber for clipboard
  61.   screen   - screen on which BitMap is to be used. May be NULL.
  62.   Flags    - Flags to control image loading
  63.       Default is to remap to screen palette and return a bitmap in BitMap
  64.       Only way to free is to call FreeMPImage().
  65.  
  66.       MPIF_EGS         - Return E_EBitMap rather than BitMap. 
  67.           Overrides MPIF_RGB
  68.       MPIF_CLONEBITMAP - You are free to zero BitMap/EGS_BitMap before
  69.           calling FreeMPImage(). You must then call FreeBitMap() or 
  70.           E_DisposeBitMap() yourself. Ignored for MPIF_RGB/GREY. If screen
  71.           supplied then clone is screen depth deep if possible.
  72.       MPIF_NOREMAP     - Don't remap to the current screen colors. Ignored
  73.           for MPIF_EGS/RGB/GREY. Returns error if 24 bit input.
  74.       MPIF_RGB         - return Red, Green, Blue instead of BitMap.
  75.       MPIF_GREY        - return Red, Green, Blue instead of BitMap. If
  76.           image is greyscale then Red, Green and Blue will be the same
  77.           and GreyScale will be TRUE
  78.       MPIF_FORCEGREY   - As MPIF_GREY except input will always be remapped
  79.           to greyscale.
  80.       MPIF_LINEARGREY  - Use linear (not colour based) mapping (V5.0)
  81.  
  82.    RESULT
  83.   MPi - Pointer to an MPImage structure holding the image data.
  84.         NULL if an error occurs. Use MPImageErrorMessage() to get error.
  85.  
  86.    EXAMPLE
  87.  
  88.    NOTES
  89.   If file format is JPG and env/mpimage/djpeg is set (e.g. djpeg "%s" "%s")
  90.   and not loading a BitMap then djpeg is used.
  91.  
  92.   If file format is PNG and env/mpimage/pngtopnm is set
  93.   (e.g. pngtopnm "%s" >"%s") and not loading a BitMap then pngtopnm is used.
  94.  
  95.   Other fileformats are IBLM (depth 1 to 8 and 24, EHB, HAM6 and HAM8),
  96.   PBM (all types) and any picture datatype. With dctv.library(3) can also
  97.   load DCTV images.
  98.  
  99.    BUGS
  100.   Waits 20 seconds for djpeg/pngtopnm to start then aborts.
  101.   Fails to set an error message if failure loading from clipboard.
  102.   Can also fail to set an error message in other (unknown) circumstances.
  103.  
  104.    SEE ALSO
  105.   FreeMPImage(),MPImageErrorMessage,graphics.library/FreeBitMap(),
  106.   egs.library/E_DisposeBitMap(),MPImageErrorMessage().
  107.  
  108. MPImage.library/MPImageErrorMessage        MPImage.library/MPImageErrorMessage
  109.  
  110.    NAME   
  111.   MPImageErrorMessage -- Return the last error set by MPImage.library. (V3)
  112.  
  113.    SYNOPSIS
  114.   msg = MPImageErrorMessage()
  115.   D0
  116.  
  117.   char *MPImageErrorMessage( void );
  118.  
  119.    FUNCTION
  120.   Returns the last error message set by this opener of MPImage.library.
  121.  
  122.    INPUTS
  123.   None.
  124.  
  125.    RESULT
  126.   Formatted Error Message.
  127.  
  128.    EXAMPLE
  129.  
  130.    NOTES
  131.  
  132.    BUGS
  133.  
  134.    SEE ALSO
  135.  
  136. MPImage.library/MPPlanarToChunky              MPImage.library/MPPlanarToChunky
  137.  
  138.    NAME   
  139.   MPPlanarToChunky -- Convert a bitmap to a chunky buffer (V5)
  140.  
  141.    SYNOPSIS
  142.   MPPlanarToChunky( bitmap, chunky, width, height )
  143.                     A0      A1      D0     D1
  144.  
  145.   void MPPlanarToChunky( struct BitMap *, UBYTE *, UWORD, UWORD);
  146.  
  147.    FUNCTION
  148.   Converts a BitMap to a chunky buffer.
  149.  
  150.    INPUTS
  151.   bitmap - Pointer to a standard bitmap.
  152.   chunky - Pointer to a chunky buffer of sufficient size.
  153.   width  - Width of bitmap.
  154.   height - Height of bitmap.
  155.  
  156.    RESULT
  157.   None.
  158.  
  159.    EXAMPLE
  160.  
  161.    NOTES
  162.  
  163.    BUGS
  164.  
  165.    SEE ALSO
  166.  
  167. MPImage.library/RescaleMPImage                  MPImage.library/RescaleMPImage
  168.  
  169.    NAME   
  170.   RescaleMPImage -- Scales an image created by LoadMPImage() (V3)
  171.  
  172.    SYNOPSIS
  173.   error = RescaleMPImage(MPi, x, y)
  174.   D0                     A0   D0 D1
  175.  
  176.   BOOL RescaleMPImage(struct MPImage *, UWORD, UWORD);
  177.  
  178.    FUNCTION
  179.   Scales an Image loaded by LoadMPImage() to new width and height.
  180.  
  181.    INPUTS
  182.   MPi - Image loaded by LoadMPImage
  183.   x   - New width of image
  184.   y   - New height of image
  185.  
  186.    RESULT
  187.   error - 1 for success, 0 for failure.
  188.           Use MPImageErrorMessage() to get error.
  189.  
  190.    EXAMPLE
  191.  
  192.    NOTES
  193.   Rescaling of bitmaps is done using BitMapScale().
  194.   Other rescaling is done using custom code with smoothing.
  195.  
  196.   If this function fails then the MPImage is no longer usable and
  197.   FreeMPImage() should be called to free it.
  198.  
  199.   Version 4.3 is faster for RGB.
  200.  
  201.    BUGS
  202.   Bitmaps may not scale smoothly.
  203.   The rescaling of EGS images is not efficent.
  204.  
  205.    SEE ALSO
  206.   LoadMPImage(),MPImageErrorMessage(),FreeMPImage(),
  207.   graphics.library/BitMapScale().
  208.  
  209. MPImage.library/SaveMPImageA                      MPImage.library/SaveMPImageA
  210.  
  211.    NAME   
  212.   SaveMPImageA -- Save an image in various formats. (V3)
  213.   SaveMPIMage -- Varargs version of SaveMPImageA (V3)
  214.  
  215.    SYNOPSIS
  216.   succ = SaveMPImageA( file,red,green,blue,width,height,taglist)
  217.   D0                   A0   A1  A2    A3   D0    D1     A5
  218.  
  219.   BOOL SaveMPImageA( UBYTE *,UBYTE *,UBYTE *,UBYTE *,
  220.                                    UWORD,UWORD,struct TagItem *);
  221.  
  222.   succ = SaveMPImage( file,red,green,blue,width,height,Tag1, ...)
  223.  
  224.   BOOL SaveMPImage( UBYTE *,UBYTE *,UBYTE *,UBYTE *,
  225.                                    UWORD,UWORD,ULONG,...);
  226.  
  227.    FUNCTION
  228.   Saves/displays an image held in chunky buffers.
  229.  
  230.    INPUTS
  231.   file    - filename to save file as. If NULL or "" then image is
  232.             displayed on a custom screen.
  233.   red     - red chunky input.
  234.   green   - green chunky input.
  235.   blue    - blue chunky input.
  236.   width   - width of chunky buffers
  237.   height  - height of chunky buffers.
  238.   taglist - pointer to TagItem array.
  239.  
  240.   Tags are:
  241.  
  242.   MPIS_MODE   - Data is ULONG CAMG of output IFF file/screen EHB and HAM
  243.                 will be added if required. If not supplied then
  244.                 MPIS_MODENAME will be used. If that is not supplied then
  245.                 a CAMG mode will be generated.
  246.   MPIS_MODENAME - Data is char * mode name of CAMG of output. Invalid
  247.                   names are ignored.
  248.   MPIS_FORMAT - Data is char * specifying output format.
  249.                 Default is MPI_BW16. Values are:
  250.                 MPI_BW16   - "BW16"   - 16 colour ILBM grey scale.
  251.                 MPI_BW256  - "BW256"  - 256 colour ILBM grey scale.
  252.                 MPI_HAM6   - "HAM6"   - HAM6 with fixed (internal) palette.
  253.                 MPI_HAM6P  - "HAM6P"  - HAM6 with generated or supplied
  254.                                         palette - see MPIS_PALETTE.
  255.                 MPI_HAM8   - "HAM8"   - HAM8 with fixed (internal) palette.
  256.                 MPI_HAM8P  - "HAM8P"  - HAM8 with generated or supplied
  257.                                         palette - see MPIS_PALETTE.
  258.                 MPI_ILBM24 - "ILBM24" - 24 bit ILBM.
  259.                 MPI_PPM    - "PPM"    - P6 (or P5 if red,green and blue are
  260.                                         the same).
  261.                 MPI_COLOUR - "COLOUR" - ILBM with generated or supplied
  262.                                         palette - see MPIS_PALETTE.
  263.                 MPI_EHB    - "EHB"    - EHB with generated or supplied
  264.                                         palette - see MPIS_PALETTE.
  265.                 MPI_JPEG   - "JPEG"   - JPEG see NOTES.
  266.                 MPI_PNM    - "PNG"    - PNG see NOTES.
  267.                 MPI_DCTV3  - "DCTV3"  - DCTV 3 bit plane format
  268.                 MPI_DCTV4  - "DCTV4"  - DCTV 4 bit plane format
  269.   MPIS_PALETTE - Data is char * name of ILBM to load palette from.
  270.   MPIS_COLOURS - Data is ULONG number of colours for MPI_COLOUR.
  271.                  Default is is number of colours in MPIS_PALETTE if
  272.                  supplied, otherwise 16. If greater than that from
  273.                  MPIS_PALETTE then ignored.
  274.   MPIS_12BIT   - Data is BOOL. If TRUE then use faster 12bit colour palette
  275.                  generating algorithm for MPI_COLOUR and MPI_EHB. Default
  276.                  is FALSE to use 18bit algorithm.
  277.   MPIS_LINEAR  - Data is BOOL. If TRUE then for BW16/BW256 use linear
  278.                  (not colour based) mapping. (V5.0)
  279.   MPIS_GREYMAP - Data is UBYTE *. For BW16/BW256 palette map. Must point
  280.                  to at least 16 of value 0 to 15 for BW16, 256 bytes of
  281.                  0 to 255 for BW255. (V5.0)
  282.                  Format is e.g. 0,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1
  283.                    Colour 0 will be black
  284.                    Colour 1 will be white
  285.                    etc.
  286.                  This is the opposite to which you may expect!
  287.  
  288.    RESULT
  289.   error - 1 for success, 0 for failure.
  290.           Use MPImageErrorMessage() to get error.
  291.  
  292.    EXAMPLE
  293.  
  294.    NOTES
  295.   If MPIS_FORMAT is BW16 or BW256 and red,green and blue are the same then
  296.   a more efficent algorithm is used.
  297.  
  298.   When displaying on screen click in the top left and press a key to exit.
  299.  
  300.   If file format is JPEG and env/mpimage/cjpeg is set (e.g. cjpeg "%s" "%s")
  301.   then cjpeg is used.
  302.  
  303.   If file format is PNG and env/mpimage/pnmtopng is set
  304.   (e.g. 'pnmtopng "%s" >"%s"') then pnmtopng is used.
  305.  
  306.    BUGS
  307.   Does not work for images > 1024 wide (except PPM/JPEG/PNG).
  308.   The palette file requires a body which is loaded and then discarded.
  309.  
  310.   Waits 20 seconds for cjpeg/pnmtopng to start then aborts. This check is
  311.   not fool proof and the PIPE:xxx can be left hanging.
  312.  
  313.   Prior to version 4.3 fails to determine a screen mode correctly.
  314.  
  315.    SEE ALSO
  316.   MPImageErrorMessage().
  317.  
  318. MPImage.library/SetMPImageScreen              MPImage.library/SetMPImageScreen
  319.  
  320.    NAME   
  321.   SetMPImageScreen -- Sets the Screen name for progress requesters (V3)
  322.  
  323.    SYNOPSIS
  324.   SetMPImageScreen(ScreenName,Flags)
  325.                    A0         D0
  326.  
  327.   void SetMPImageScreen(char *, ULONG);
  328.  
  329.    FUNCTION
  330.   Sets the Screen Name for progress requesters for this opener.
  331.  
  332.    INPUTS
  333.   ScreenName - Name of Public Screen, NULL for default
  334.   Flags      - 0 - Do not show progress requesters (default)
  335.              - MPIF_PROGRESS - Do show progress requesters
  336.                                (except for non remapped bitmaps).
  337.  
  338.    RESULT
  339.   None.
  340.  
  341.    EXAMPLE
  342.  
  343.    NOTES
  344.   ScreenName must remain valid while MPImage.library is open.
  345.  
  346.    BUGS
  347.  
  348.    SEE ALSO
  349.  
  350.