gml_Bitmap_base.h

Go to the documentation of this file.
00001 /**
00002  * @file gml_Bitmap_base.h
00003  *
00004  *    Basic operation on gml_TBitmaps: allocation, de-allocation.
00005  *
00006  *  Copyright (c) 2003 CLIPS-IMAG
00007  *
00008  *  See the file "gml_LicenseTerms.txt" for information on usage and redistribution
00009  *  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00010  *
00011  *  August 26, 2004 (FB)
00012  *    Made this header file a C (versus C++) header.
00013  *    Changed the "bitmap" parameter of "gml_BitmapAllocAndInit" and
00014  *      "gml_BitmapTestDisposeAndFree" from "gml_TBitmap*&" to "gml_TBitmap**".
00015  *    Centralized all bitmap related error codes in this file (copied from
00016  *      "gml/image/gml_Bitmap_encodings.h" and "gml/image/gml_Bitmap_scans.h").
00017  *    Exported the "gml_BitmapInitialize" function. It must be called before returning
00018  *      any of the previously mentionned error code.
00019  *
00020  *  Created on May 20, 2003 (FB).
00021  */
00022 
00023 #ifndef __GML_BITMAP_BASE__
00024 #define __GML_BITMAP_BASE__
00025 
00026 #include "gml/base/gml_Types.h"
00027 #include "gml/base/gml_Errors.h"
00028 #include "gml/image/gml_Bitmap.h"
00029 
00030 
00031 /* Errors */
00032 
00033 extern gml_TError       gml_gBitmap_rowOffsetTooSmall;
00034 extern gml_TError       gml_gBitmap_notSameSize;
00035 extern gml_TError       gml_gBitmap_invalidROI;
00036 extern gml_TError       gml_gBitmap_unknownEncoding;
00037 extern gml_TError       gml_gBitmap_unsupportedEncoding;
00038 extern gml_TError       gml_gBitmap_wrongChannelNumber;
00039 
00040 
00041 
00042 /**
00043  * gml_BitmapInitialize --
00044  *
00045  *  Initialize gml_TBitmap error codes. Must be called in order to associate
00046  *  error messages to error codes. Can be called many times (simply returns
00047  *  if already initialized).
00048  */
00049 GML_EXTERN_C
00050 void gml_BitmapInitialize ();
00051 
00052 
00053 /** 
00054  *  When used as the <rowOffset> parameter of gml_BitmapInit(), specifies that
00055  *  the created bitmap should have 32-bit word-aligned lines.
00056  */
00057 #define GML_BITMAP_PADDING_AUTO   (-1)
00058 
00059 /** 
00060  *  When used as the <rowOffset> parameter of gml_BitmapInit(), specifies that
00061  *  the created bitmap should have unaligned lines.
00062  */
00063 #define GML_BITMAP_PADDING_NONE   (-2)
00064 
00065 /**
00066  * gml_BitmapInit --
00067  *
00068  *  Initialize the fields of a gml_TBitmap and allocates the memory for the pixels.
00069  *  <bitmap> must be allocated (but not initialized).
00070  *
00071  *  If <rowOffset> is GML_BITMAP_PADDING_AUTO, it is computed by <gml_BitmapInit>
00072  *  as the smallest possible multiple of 4.
00073  *
00074  *  If <rowOffset> is GML_BITMAP_PADDING_NONE, it is computed by <gml_BitmapInit>
00075  *  as the smallest possible value (no padding between lines).
00076  *    
00077  */
00078 GML_EXTERN_C
00079 gml_TError gml_BitmapInit  (gml_TBitmap*        bitmap,
00080                             int                 width,
00081                             int                 height,
00082                             gml_TPixelEncoding  encoding,
00083                             int                 rowOffset,
00084                             int                 fromTop);
00085 
00086 /**
00087  * gml_BitmapDispose --
00088  *
00089  *   Release the bitmap's buffer.
00090  */
00091 GML_EXTERN_C
00092 void gml_BitmapDispose  (gml_TBitmap* bitmap);
00093 
00094 
00095 
00096 /**
00097  * gml_BitmapZero --
00098  *
00099  *  Set all bitmap fields to 0.
00100  */
00101 GML_EXTERN_C
00102 void gml_BitmapZero  (gml_TBitmap* bitmap);
00103 
00104 
00105 
00106 /**
00107  * gml_BitmapAllocAndInit --
00108  *
00109  *  Same as <gml_BitmapInit> but the bitmap structure is first allocated.
00110  */
00111 GML_EXTERN_C
00112 gml_TError gml_BitmapAllocAndInit  (gml_TBitmap**       bitmap,
00113                                     int                 width,
00114                                     int                 height,
00115                                     gml_TPixelEncoding  encoding,
00116                                     int                 rowOffset,
00117                                     int                 fromTop);
00118 
00119 /**
00120  * gml_BitmapTestDisposeAndFree --
00121  *
00122  *  Same as <gml_BitmapDispose> but returns immediately if the pointer to the 
00123  *  bitmap is NULL, and if not, the bitmap structure is finally freed (and
00124  *  its pointer set to NULL).
00125  */
00126 GML_EXTERN_C
00127 void gml_BitmapTestDisposeAndFree (gml_TBitmap** bitmap);
00128 
00129 
00130 
00131 
00132 /**
00133  * gml_BitmapPixel --
00134  *
00135  *  Return the address of the pixel at (x,y) in the argument bitmap.
00136  *  Will call abort() if (x,y) is outside the bitmap boundaries.
00137  *  Warning: calling this is slow, don't use in a tight loop!
00138  */
00139 GML_EXTERN_C
00140 void* gml_BitmapPixel  (gml_TBitmap* bitmap, int x, int y);
00141 
00142 
00143 #endif
00144