//docs/MPImage.doc/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().