TABLE OF CONTENTS MPImage.library/--background-- MPImage.library/FreeMPImage MPImage.library/LoadMPImage MPImage.library/MPChunkyToPlanar MPImage.library/MPGreyToPal MPImage.library/MPImageErrorMessage MPImage.library/MPPalToGrey MPImage.library/MPPalToPal MPImage.library/MPPalToRGB MPImage.library/MPPlanarToChunky MPImage.library/MPProgressHook MPImage.library/MPRGBToGrey MPImage.library/MPRGBToPal MPImage.library/MPScaleGrey MPImage.library/MPScaleRGB MPImage.library/RescaleMPImage MPImage.library/SaveMPImageA MPImage.library/SetMPImageScreen MPImage.library/--background-- MPImage.library/--background-- Version 7.3 - fixed enforcer hit when no progress requester. - Opens locale.library(38) to work on OS3.0. MPImage.library lets you load save and process images. Stuctures/Formats: RGB Chunky This is held as seperate Red Green and Blue UBYTE *, with a Width and Height Grey Chunky This is held as one Grey UBYTE * (often called red), with a Width and a Height. Palette This is held as one UBYTE[768] (sometimes called red, a Width and Height, and a UBYTE *Palette. The palette holds the red palette in [0] to [255], the green palette in [256] to [511] and the blue palette in [512] to [767]. There may also be a camg (or modeid) and a number of colours, or number of planes. These are required for EHB and HAM images. Bitmap A normal planar bit map. This also has other fields as for Palette. EGSBitMap A standard EGSBitMap. MPImage This holds one of RGB, Grey, Bitmap or EGSBitMap. MPProcess This holds the RGB pointers and width and height. It is used for some processing functions. Image Loading: LoadMPImage() Loads an image from disc/clipboard. It loads various formats. Returns BitMap, RGB, GreyScale or EGSBitMap. Image Saving: SaveMPImage() Can save RGB/GreyScale to disc. It saves in various formats. ImageScaling: RescaleMPImage() Scales a loaded image (any format). Displaying Images SaveMPImage() Can display RGB/GreyScale Buffers. Miscellaneous: FreeMPImage()  Frees a loaded image. SetMPImageScreen() Sets the screen for the progress requester. MPProgressHook() Sets a progress hook for messages. MPImageErrorMessage() Returns the last error message. Planar/Chunky Conversion: MPPlanarToChunky() Converts a BitMap to a chunky buffer. MPChunkyToPlanar() Converts a chunky buffer to a BitMap. SaveMPImage() Can convert RGB Buffers to a BitMap. Image processing: Image processing is done on chunky buffers; RGB, GreyScale or Palette based. The following convert between these formats. MPGreyToPal() GreyScale to Palette. MPPalToGrey() Palette to GreyScale. MPPalToPal() Palette to a different Palette. MPPalToRGB() Palette to RGB. MPRGBToGrey() RGB To Grey. MPRGBToPal() RGB To Palette. Buffers can also be scaled: MPScaleGrey() Scales one buffer. MPScaleRGB() Scales 3 buffers. Same as 3 calls to MPScaleGrey() but faster. Summary: Input Output Format Format !Disc! RGB !Gray !Palette!BitMap!EGSBitMap!MPImage!Screen ---------!----!-----!-----!-------!------!---------!-------!------ Disc/Clip! !1* !1* ! !1* !1* !1 ! RGB !2 !13,3*!10 !11 !2 ! ! !2 Gray !2 !x !12,3*!6 !2 ! ! !2 Palette ! !9 !7 !8 !5 ! ! ! BitMap ! ! ! !4 !3*,o ! ! ! EGSBitMap! ! ! ! ! !3* ! ! MPImage !2+ !+ !+ !# !+ !+ !3 !2+ 1 - LoadMPImage() 2 - SaveMPImage() 3 - RescaleMPImage() 4 - MPPlanarToChunky() 5 - MPChunkyToPlanar() 6 - MPGreyToPal() 7 - MPPalToGrey() 8 - MPPalToPal() 9 - MPPalToRGB() 10 - MPRGBToGrey() 11 - MPRGBToPal() 12 - MPScaleGrey() 13 - MPScaleRGB() * - As part of an MPImage + - Depends on parameters to LoadMPImage x - Easy - no function supplied o - See BitMapScale() # - Depends on LoadMPImage, use 11,6,8 or 4 MPImage.library/FreeMPImage MPImage.library/FreeMPImage NAME FreeMPImage -- Free an image loaded using LoadMPImage() (V3) SYNOPSIS FreeMPImage( MPi ) A0 void FreeMPImage( struct MPImage * ); FUNCTION Frees all data associated loaded with an image using LoadMPImage(). INPUTS MPi - structure returned by LoadMPImage(). RESULT None. EXAMPLE NOTES BUGS SEE ALSO LoadMPImage() MPImage.library/LoadMPImage MPImage.library/LoadMPImage NAME LoadMPImage -- Load an image in various formats (V4) SYNOPSIS MPi = LoadMPImage( filename,screen,Flags ) D0 A0 A1 D0 struct MPImage *LoadMPImage ( const char *,struct Screen *,ULONG); FUNCTION Load an image in BitMap, EGSBitMap or RGB format. INPUTS filename - name of file from which to load image - -c or -cnumber for clipboard screen - screen on which BitMap is to be used. May be NULL. Flags - Flags to control image loading Default is to remap to screen palette and return a bitmap in BitMap Only way to free is to call FreeMPImage(). MPIF_EGS - Return E_EBitMap rather than BitMap. Overrides MPIF_RGB MPIF_CLONEBITMAP - You are free to zero BitMap/EGS_BitMap before calling FreeMPImage(). You must then call FreeBitMap() or E_DisposeBitMap() yourself. Ignored for MPIF_RGB/GREY. If screen supplied then clone is screen depth deep if possible. MPIF_NOREMAP - Don't remap to the current screen colors. Ignored for MPIF_EGS/RGB/GREY. Returns error if 24 bit input. MPIF_RGB - return Red, Green, Blue instead of BitMap. MPIF_GREY - return Red, Green, Blue instead of BitMap. If image is greyscale then Red, Green and Blue will be the same and GreyScale will be TRUE MPIF_FORCEGREY - As MPIF_GREY except input will always be remapped to greyscale. MPIF_LINEARGREY - Use linear (not colour based) mapping (V5.0) RESULT MPi - Pointer to an MPImage structure holding the image data. NULL if an error occurs. Use MPImageErrorMessage() to get error. EXAMPLE NOTES If file format is JPG and env/mpimage/djpeg is set (e.g. djpeg "%s" "%s") and not loading a BitMap then djpeg is used. If file format is PNG and env/mpimage/pngtopnm is set (e.g. pngtopnm "%s" >"%s") and not loading a BitMap then pngtopnm is used. Other fileformats are IBLM (depth 1 to 8 and 24, EHB, HAM6 and HAM8), PBM (all types) and any picture datatype. With dctv.library(3) can also load DCTV images. BUGS Waits 20 seconds for djpeg/pngtopnm to start then aborts. Fails to set an error message if failure loading from clipboard. Can also fail to set an error message in other (unknown) circumstances. SEE ALSO FreeMPImage(),MPImageErrorMessage,graphics.library/FreeBitMap(), egs.library/E_DisposeBitMap(),MPImageErrorMessage(). MPImage.library/MPChunkyToPlanar MPImage.library/MPChunkyToPlanar NAME MPChunkyToPlanar -- Convert a chunky buffer to a BitMap (V7) SYNOPSIS MPChunkyToPlanar( chunky, bitmap, width, height ) A0 A1 D0 D1 void MPPlanarToChunky( UBYTE *, struct BitMap *, UWORD, UWORD); FUNCTION Converts a chunky buffer to a BitMap. INPUTS chunky - Pointer to a chunky buffer of sufficient size. bitmap - Pointer to a standard bitmap (of sufficient size). width - Width of buffer. height - Height of buffer. RESULT None. EXAMPLE NOTES BUGS SEE ALSO MPPlanarToChunky(). MPImage.library/MPGreyToPal MPImage.library/MPGreyToPal NAME MPGreyToPal -- Convert GreyScale image to a palette (V7) SYNOPSIS MPGreyToPal( MPp,maxcol,pal ) A0 D0 A1 void MPGreyToPal ( struct MPProcess *,ULONG,UBYTE *,BOOL); FUNCTION Convert Grey to a palette. INPUTS MPp - Contains (in Read) the GreyScale chunky pixels and the Width and Height maxcol - The number of colours in the palette. pal - The palette. This is a 768 byte array. r[0] to r[maxcol] hold the Red palette r[256] to r[256+maxcol] hold the Green palette r[512] to r[512+maxcol] hold the Blue palette RESULT The data pointed to by MPp->Red is updated to the palette mapped image. EXAMPLE NOTES BUGS Not tested. SEE ALSO MPRGBToPal(). MPImage.library/MPImageErrorMessage MPImage.library/MPImageErrorMessage NAME MPImageErrorMessage -- Return the last error set by MPImage.library. (V3) SYNOPSIS msg = MPImageErrorMessage() D0 char *MPImageErrorMessage( void ); FUNCTION Returns the last error message set by this opener of MPImage.library. INPUTS None. RESULT Formatted Error Message. EXAMPLE NOTES BUGS SEE ALSO MPImage.library/MPPalToGrey MPImage.library/MPPalToGrey NAME MPPalToGrey -- Convert palette image to GreyScale (V7) SYNOPSIS MPPalToGrey(Width,Height,pal,chunky,nPlanes,camg,Linear); D0 D1 A0 A1 D2 D3 D4 void MPPalToGrey (UWORD,UWORD,UBYTE *,UBYTE *,UWORD,ULONG,BOOL); FUNCTION Convert palette image to GreyScale. INPUTS Width - Width of image. Height - Height of image. pal - The current palette. This is a 768 byte array. [0] to [...] hold the Red palette [256] to [256+...] hold the Green palette [512] to [512+...] hold the Blue palette chunky - The current chunky pixels. nPlanes - The number of planes in the current palette. camg - The camg of the current palette. Linear - If True then map linear, otherwise give more weight to Green. RESULT The data pointed to by chunky is updated to the GreyScale pixels. EXAMPLE NOTES nPlanes and camg are required to cater for EHB and HAM. BUGS Not tested. SEE ALSO MPPalToRGB(). MPImage.library/MPPalToPal MPImage.library/MPPalToPal NAME MPPalToPal -- Convert image with one palette to another palette (V7) SYNOPSIS MPPalToPal(OldPal,OldCols,NewPal,NewCols,chunky,Width,Height, nPlanes,camg); A0 D0 A1 D1 A2 D2 D3 D4 D5 void MPPalToPal ( UBYTE *,ULONG,UBYTE *,ULONG,UBYTE *,UWORD,UWORD, UWORD, ULONG); FUNCTION Convert image with one palette to another palette. INPUTS OldPal - The current palette. This is a 768 byte array. [0] to [maxcol] hold the Red palette [256] to [256+maxcol] hold the Green palette [512] to [512+maxcol] hold the Blue palette OldCols - The number of colours in the current palette. NewPal - The new palette. This is a 768 byte array. [0] to [maxcol] hold the Red palette [256] to [256+maxcol] hold the Green palette [512] to [512+maxcol] hold the Blue palette NewCols - The number of colours in the new palette. chunky - The chunky pixels. Width - The width of the image. Height - The height of the image. nPlanes - The number of planes in the current palette camg - The camg of the current palette RESULT The data pointed to by chunky is updated to the new palette. EXAMPLE NOTES nPlanes and camg are required to cater for EHB and HAM. BUGS Not tested. SEE ALSO MPImage.library/MPPalToRGB MPImage.library/MPPalToRGB NAME MPPalToRGB -- Convert palette image to RGB (V7) SYNOPSIS MPPalToRGB(MPp,pal,chunky,nPlanes,camg); A0 A1 A2 D0 D1 void MPPalToRGB ( struct MPProcess *,UBYTE *,UBYTE *,UWORD,ULONG); FUNCTION Convert palette image to RGB. INPUTS MPp - Holds buffers to store the Red, Green and Blue pixels and the Width and the Height. pal - The current palette. This is a 768 byte array. [0] to [...] hold the Red palette [256] to [256+...] hold the Green palette [512] to [512+...] hold the Blue palette chunky - The current chunky pixels. nPlanes - The number of planes in the current palette camg - The camg of the current palette RESULT The data pointed to by MPp->Red, MPp->Green and MPp->Blue are updated to the RGB pixels. EXAMPLE NOTES nPlanes and camg are required to cater for EHB and HAM. BUGS Not tested. SEE ALSO MPPalToGrey(). MPImage.library/MPPlanarToChunky MPImage.library/MPPlanarToChunky NAME MPPlanarToChunky -- Convert a bitmap to a chunky buffer (V5) SYNOPSIS MPPlanarToChunky( bitmap, chunky, width, height ) A0 A1 D0 D1 void MPPlanarToChunky( struct BitMap *, UBYTE *, UWORD, UWORD); FUNCTION Converts a BitMap to a chunky buffer. INPUTS bitmap - Pointer to a standard bitmap. chunky - Pointer to a chunky buffer of sufficient size. width - Width of bitmap. height - Height of bitmap. RESULT None. EXAMPLE NOTES BUGS SEE ALSO MPChunkyToPlanar(). MPImage.library/MPProgressHook MPImage.library/MPProgressHook NAME MPProgressHook -- Sets the Progress Hook (V6) SYNOPSIS MPProgressHook(Hook) A0 void MPProgressHook(struct Hook*); FUNCTION Sets the Hook to call for progress messages. INPUTS Hook - Hook to call RESULT None. EXAMPLE NOTES Called with... object = MPIP_MAX, (ULONG)message = max-progress object = MPIP_MAX, (ULONG)message = curr-progress object = MPIP_CURR,(UBYTE *)message = Progress-Message BUGS SEE ALSO MPImage.library/MPRGBToGrey MPImage.library/MPRGBToGrey NAME MPRGBToGrey -- Convert RGB image to GreyScale (V7) SYNOPSIS MPRGBToGrey(MPp,Linear); A0 D0 void MPRGBToGrey (struct MPProcess *,BOOL); FUNCTION Convert RGB image to GreyScale. INPUTS MPp - Contains the Red,Green and Blue chunky pixels and the Width and Height Linear - If True then map linear, otherwise give more weight to Green. RESULT The data pointed to by MPp->Red is updated to the GreyScale pixels. EXAMPLE NOTES BUGS Not tested. SEE ALSO MPImage.library/MPRGBToPal MPImage.library/MPRGBToPal NAME MPRGBToPal -- Convert RGB image to a palette (V7) SYNOPSIS MPRGBToPal( MPp,maxcol,pal,bit12 ) A0 D0 A1 D1 void MPRGBToPal ( struct MPProcess *,ULONG,UBYTE *,BOOL); FUNCTION Convert RGB to a palette. INPUTS MPp - Contains the Red,Green and Blue chunky pixels and the Width and Height maxcol - The number of colours in the palette. pal - The palette. This is a 768 byte array. pal[0] to pal[maxcol] hold the Red palette pal[256] to pal[256+maxcol] hold the Green palette pal[512] to pal[512+maxcol] hold the Blue palette bit12 - If set then only the top 4 bits of the palette are used and the mapping is far quicker. RESULT The data pointed to by MPp->Red is updated to the palette mapped image. EXAMPLE NOTES If there is insufficient memory then bit12 is treated as false. BUGS Not tested. SEE ALSO MPGreyToPal(). MPImage.library/MPScaleGrey MPImage.library/MPScaleGrey NAME MPScaleGrey -- Scales a GreyScale image (V7) SYNOPSIS MPScaleGrey( Old,New,OWidth,OHeight,NWidth,NHeight,Temp) A0 A1 D0 D1 D2 D3 A2 void MPScaleGrey ( UBYTE *,UBYTE *,UWORD,UWORD,UWORD,UWORD,UBYTE *); FUNCTION Scales an RGB image. INPUTS Old - Contains existing chunky pixels. New - Buffer for the new chunky pixels. OWidth - Current Width. OHeight - Current Height. NWidth - New Width. NHeight - New Height. Temp - Temporary buffer sized for the new image. RESULT The data pointed to by New is updated to the scaled image. EXAMPLE NOTES BUGS Not tested. SEE ALSO MPScaleRGB(). MPImage.library/MPScaleRGB MPImage.library/MPScaleRGB NAME MPScaleRGB -- Scales an RGB image (V7) SYNOPSIS MPScaleRGB( Old,New,Temp) A0 A1 A2 void MPScaleRGB ( struct MPProcess *,struct MPProcess *,struct MPProcess *); FUNCTION Scales an RGB image. INPUTS Old - Contains the Red,Green and Blue chunky pixels and the Width and Height of the current image. New - Contains the Red,Green and Blue chunky pixels and the Width and Height for the new image. Temp - Contains 3 temporary buffers sized for the new image. RESULT The data pointed to by New->Red/Green/Blue is updated to the scaled image. EXAMPLE NOTES BUGS Not tested. SEE ALSO MPScaleGrey(). MPImage.library/RescaleMPImage MPImage.library/RescaleMPImage NAME RescaleMPImage -- Scales an image created by LoadMPImage() (V3) SYNOPSIS error = RescaleMPImage(MPi, x, y) D0 A0 D0 D1 BOOL RescaleMPImage(struct MPImage *, UWORD, UWORD); FUNCTION Scales an Image loaded by LoadMPImage() to new width and height. INPUTS MPi - Image loaded by LoadMPImage x - New width of image y - New height of image RESULT error - 1 for success, 0 for failure. Use MPImageErrorMessage() to get error. EXAMPLE NOTES Rescaling of bitmaps is done using BitMapScale(). Other rescaling is done using custom code with smoothing. If this function fails then the MPImage is no longer usable and FreeMPImage() should be called to free it. Version 4.3 is faster for RGB. BUGS Bitmaps may not scale smoothly. The rescaling of EGS images is not efficent. SEE ALSO LoadMPImage(),MPImageErrorMessage(),FreeMPImage(), graphics.library/BitMapScale(). MPImage.library/SaveMPImageA MPImage.library/SaveMPImageA NAME SaveMPImageA -- Save an image in various formats. (V3) SaveMPIMage -- Varargs version of SaveMPImageA (V3) SYNOPSIS succ = SaveMPImageA( file,red,green,blue,width,height,taglist) D0 A0 A1 A2 A3 D0 D1 A5 BOOL SaveMPImageA( UBYTE *,UBYTE *,UBYTE *,UBYTE *, UWORD,UWORD,struct TagItem *); succ = SaveMPImage( file,red,green,blue,width,height,Tag1, ...) BOOL SaveMPImage( UBYTE *,UBYTE *,UBYTE *,UBYTE *, UWORD,UWORD,ULONG,...); FUNCTION Saves/displays an image held in chunky buffers. INPUTS file - filename to save file as. If NULL or "" then image is displayed on a custom screen, or returned in BitMap (V7.0) red - red chunky input. green - green chunky input. blue - blue chunky input. width - width of chunky buffers height - height of chunky buffers. taglist - pointer to TagItem array. Tags are: MPIS_MODE - Data is ULONG CAMG of output IFF file/screen EHB and HAM will be added if required. If not supplied then MPIS_MODENAME will be used. If that is not supplied then a CAMG mode will be generated. MPIS_MODENAME - Data is char * mode name of CAMG of output. Invalid names are ignored. MPIS_FORMAT - Data is char * specifying output format. Default is MPI_BW16. Values are: MPI_BW16 - "BW16" - 16 colour ILBM grey scale. MPI_BW256 - "BW256" - 256 colour ILBM grey scale. MPI_HAM6 - "HAM6" - HAM6 with fixed (internal) palette. MPI_HAM6P - "HAM6P" - HAM6 with generated or supplied palette - see MPIS_PALETTE. MPI_HAM8 - "HAM8" - HAM8 with fixed (internal) palette. MPI_HAM8P - "HAM8P" - HAM8 with generated or supplied palette - see MPIS_PALETTE. MPI_ILBM24 - "ILBM24" - 24 bit ILBM. MPI_PPM - "PPM" - P6 (or P5 if red,green and blue are the same). MPI_COLOUR - "COLOUR" - ILBM with generated or supplied palette - see MPIS_PALETTE. MPI_EHB - "EHB" - EHB with generated or supplied palette - see MPIS_PALETTE. MPI_JPEG - "JPEG" - JPEG see NOTES. MPI_PNM - "PNG" - PNG see NOTES. MPI_DCTV3 - "DCTV3" - DCTV 3 bit plane format MPI_DCTV4 - "DCTV4" - DCTV 4 bit plane format MPIS_PALETTE - Data is char * name of ILBM to load palette from. MPIS_COLOURS - Data is ULONG number of colours for MPI_COLOUR. Default is is number of colours in MPIS_PALETTE if supplied, otherwise 16. If greater than that from MPIS_PALETTE then ignored. MPIS_12BIT - Data is BOOL. If TRUE then use faster 12bit colour palette generating algorithm for MPI_COLOUR and MPI_EHB. Default is FALSE to use 18bit algorithm. MPIS_LINEAR - Data is BOOL. If TRUE then for BW16/BW256 use linear (not colour based) mapping. (V5.0) MPIS_GREYMAP - Data is UBYTE *. For BW16/BW256 palette map. Must point to at least 16 of value 0 to 15 for BW16, 256 bytes of 0 to 255 for BW255. (V5.0) Format is e.g. 0,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1 Colour 0 will be black Colour 1 will be white etc. This is the opposite to which you may expect! MPIS_OLDPALETTE - Palette to use (for HAMxP/COLOUR/EHB) (V7.0) Data is UBYTE *, red in [0] to [255], green in [256] to [511] blue in [512] to [767] MPIS_NEWPALETTE - Palette used (for HAMx/COLOUR/EHB) (V7.0) Data is UBYTE * (see MPIS_OLDPALETTE). MPIS_BITMAP - BitMap to update (for BWxx/HAMxx/COLOUR/EHB/DCTVx) (V7.0) Data is struct BitMap * Image is not displayed/saved RESULT error - 1 for success, 0 for failure. Use MPImageErrorMessage() to get error. EXAMPLE NOTES If MPIS_FORMAT is BW16 or BW256 and red,green and blue are the same then a more efficent algorithm is used. When displaying on screen click in the top left and press a key to exit. If file format is JPEG and env/mpimage/cjpeg is set (e.g. cjpeg "%s" "%s") then cjpeg is used. If file format is PNG and env/mpimage/pnmtopng is set (e.g. 'pnmtopng "%s" >"%s"') then pnmtopng is used. BUGS Does not work for images > 1024 wide (except PPM/JPEG/PNG). The palette file requires a body which is loaded and then discarded. Waits 20 seconds for cjpeg/pnmtopng to start then aborts. This check is not fool proof and the PIPE:xxx can be left hanging. Prior to version 4.3 fails to determine a screen mode correctly. V7.0 did not handle MPIS_BITMAP correctly. SEE ALSO MPImageErrorMessage(). MPImage.library/SetMPImageScreen MPImage.library/SetMPImageScreen NAME SetMPImageScreen -- Sets the Screen name for progress requesters (V3) SYNOPSIS SetMPImageScreen(ScreenName,Flags) A0 D0 void SetMPImageScreen(char *, ULONG); FUNCTION Sets the Screen Name for progress requesters for this opener. INPUTS ScreenName - Name of Public Screen, NULL for default Flags - 0 - Do not show progress requesters (default) - MPIF_PROGRESS - Do show progress requesters (except for non remapped bitmaps). RESULT None. EXAMPLE NOTES ScreenName must remain valid while MPImage.library is open. BUGS SEE ALSO