gml_Bitmap_IO.h

Go to the documentation of this file.
00001 /**
00002  * @file gml_Bitmap_IO.h
00003  * 
00004  *    API for loading and saving image files, using gml_TBitmaps.
00005  *    Uses ImageMagick to handle a variety of formats, including but not
00006  *    limited to: PNG, TIFF, JPEG, PPM...
00007  *
00008  *    @todo
00009  *    provide means to control compression and quality.
00010  * 
00011  * Copyright (c) 2004 CLIPS-IMAG
00012  *
00013  * See the file "gml_LicenseTerms.txt" for information on usage and redistribution
00014  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00015  *
00016  * Created in May 2004 (JL).
00017  */
00018 
00019 #ifndef __GML_BITMAP_IO__
00020 #define __GML_BITMAP_IO__
00021 
00022 #include "gml/base/gml_Errors.h"
00023 #include "gml/base/gml_Types.h"
00024 #include "gml/image/gml_Bitmap.h"
00025 
00026 extern gml_TError gml_gBitmap_unknownFormat;
00027 extern gml_TError gml_gBitmap_badFormat;
00028 
00029 /**
00030  * gml_BitmapIO_File_Load --
00031  *
00032  *   Loads an image from a file to a bitmap structure.
00033  *   The format is infered from <format> parameter, if not NULL,
00034  *   else, if possible, from the filename, else from the first few bytes of the
00035  *   file.
00036  *
00037  *   @param  bitmap     an allocated, uninitialized bitmap. Upon successful
00038  *                      return, contains the loaded image.
00039  *   @param  format     the three-character code of the format to use, 
00040  *                      e.g. "JPG" or "TIF".
00041  *   @param  filename   the path to the file.
00042  */
00043 GML_EXTERN_C
00044 gml_TError  gml_BitmapIO_File_Load (gml_TBitmap* bitmap, char* format, char* filename);
00045 
00046 /**
00047  * gml_BitmapIO_Memory_Load --
00048  *
00049  *   Loads an image from a memory blob to a bitmap structure.
00050  *   The format is infered from <format> parameter, else from the first 
00051  *   few bytes of the blob.
00052  *   Most parameters are the same as for gml_BitmapIO_File_Load.
00053  *
00054  *   @param  data        the block of memory from which to load
00055  *   @param  bytes       the number of bytes in the block of memory
00056  */
00057 GML_EXTERN_C
00058 gml_TError gml_BitmapIO_Memory_Load (gml_TBitmap* bitmap, char* format, gml_TPointer data, UInt32 bytes);
00059 
00060 /**
00061  * gml_BitmapIO_File_Save --
00062  *
00063  *   Copy an image from a bitmap structure to a file.
00064  *   The format is infered from <format> parameter, if not NULL,
00065  *   else from the filename.
00066  *
00067  *   @param  bitmap      is the image in memory to be saved.
00068  *   @param  format      the three-character code of the format to use, 
00069  *                       e.g. "JPG" or "TIF".
00070  *   @param  parameter   for JPEG or TIFF/JPEG formats, the least 8 bits must
00071  *                       be an integer between 0 and 100 that will be used as
00072  *                       the JPEG "quality" setting.
00073  *   @param  filename    is the path to the file.
00074  */
00075 GML_EXTERN_C
00076 gml_TError  gml_BitmapIO_File_Save (gml_TBitmap* bitmap, char* format, UInt32 parameter, char* filename);
00077 
00078 /**
00079  * gml_BitmapIO_Memory_Save --
00080  *
00081  *   Copy an image from a bitmap structure to a memory blob.
00082  *   The format is infered from <format> parameter.
00083  *   Most parameters are the same as for gml_BitmapIO_File_Save.
00084  *
00085  *   @param  data        points to the block of encoded data. 
00086  *                       This block should be allocated by the
00087  *                       caller.
00088  *   @param  bytes       at call time, the available bytes in <data>.
00089  *                       upon successful return, points to the number of bytes
00090  *                       of encoded data.
00091  */
00092 GML_EXTERN_C
00093 gml_TError gml_BitmapIO_Memory_Save (gml_TBitmap* bitmap, char* format, UInt32 parameter, gml_TPointer data, UInt32* bytes);
00094 
00095 #endif
00096