geBitmap

Source file: ...\genesis3d\OpenSource\Source\Bitmap\Bitmap.h & bitmap_blitdata.h (for geBitmap_BlitData) & bitmap_gamma.h (for geBitmap_Gamma_Apply)

Contents:

Functions: Blit, BlitBestMip, BlitData, BlitBitmap, BlitMip, ClearMips, Create, CreateFromFile, CreateFromFileName, CreateFromInfo, CreateRef, Debug_GetCount, Destroy, Gamma_Apply, GetAlpha, GetAverageColor, GetBits, GetInfo, GetPalette, GetPreferredFormat, GetStreamingStatus, HasAlpha, Height, LockForRead, LockForReadNative, LockForWrite, LockForWriteFormat, MipBytes, Palette_Copy, Palette_Create, Palette_CreateCopy, Palette_CreateFromBitmap, Palette_CreateFromFile, Palette_CreateRef, Palette_Destroy, Palette_GetData, Palette_GetEntry, Palette_GetEntryColor, Palette_GetInfo, Palette_Lock, Palette_SetData, Palette_SetEntry, Palette_SetEntryColor, Palette_SetFormat, Palette_SortColors, Palette_UnLock, Palette_WriteToFile, RefreshMips, SetAlpha, SetColorKey, SetFormat, SetFormatMin, SetGammaCorrection, SetMipCount, SetPalette, SetPreferredFormat, UnLock, UnLockArray, UpdateMips, Width, WriteToFile, WriteToFileName,

Types: geBitmap, geBitmap_Palette, geBitmap_Info, geBitmap_StreamingStatus

Additions for Genesis3d v1.6: Debug_GetRefs

Notes: view

Tutorial: Charles Bloom's Tutorial 

Types:

geBitmap;

typedef struct geBitmap geBitmap;
NOTE: The contents of this structure have been intentionally left out of the interface, by the designers of this module. Think of this as a handle only.

geBitmap_Palette;

typedef struct geBitmap_Palette geBitmap_Palette;
NOTE: The contents of this structure have been intentionally left out of the interface, by the designers of this module. Think of this as a handle only.

geBitmap_Info;

typedef struct geBitmap_Info{
   int                         Width;
   int                         Height;
   int                         Stride;//stride is in* pixels*;it's the step to the next line: Stride = Width
   gePixelFormat       Format;
   int                         MinimumMip; //*including* minimumMip == 0 often
   int                         MaximumMip; //*including* maximumMip == nummips-1
   geBoolean             HasColorKey;
   uint32                    ColorKey; // meaningless unless HasColorKey;the ColorKey is a Pixel in Format
   geBitmap_Palette* Palette;
} geBitmap_Info;
Return to Contents
 
geBitmap_StreamingStatus
typedef enum {
    GE_BITMAP_STREAMING_ERROR=0,
    GE_BITMAP_STREAMING_NOT,
    GE_BITMAP_STREAMING_STARTED,
    GE_BITMAP_STREAMING_IDLE,
    GE_BITMAP_STREAMING_CHANGED,
    GE_BITMAP_STREAMING_DATADONE,
    GE_BITMAP_STREAMING_DONE,
} geBitmap_StreamingStatus;
Return to Contents

Functions:

GENESISAPI geBoolean  GENESISCC geBitmap_Blit(const geBitmap* Src, int SrcPositionX, int SrcPositionY, geBitmap* Dst, int DstPositionX, int DstPositionY, int SizeX, int SizeY );

This function blits the area (SrcPositionX, SrcPositionY)-(SrcPositionX+SizeX, SrcPositionY+SizeY) of Src to (DstPositionX, DstPositionY)-(DstPositionX+SizeX, DstPositionY+SizeY) of Dst.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Return to Contents


GENESISAPI geBoolean  GENESISCC geBitmap_BlitBestMip(const geBitmap* Src, geBitmap* Dst);

To quote the note below: This function blits the largest MIP from Src that fits into Dst.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: blits the largest mip from Src that fits in Dst
 
Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_BlitBitmap(const geBitmap* Src, geBitmap* Dst);

incomplete

This function blits the bitmap in Src to Dst.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Questions:
    How does this differ from geBitmap_BlitBestMip?  Does it copy ALL MIPs?
 
Return to Contents


GENESISAPI geBoolean  GENESISCC geBitmap_BlitMip(const geBitmap* Src, int SrcMip, geBitmap* Dst, int DstMip);

This function blits the MIP specified by SrcMip from Src to the DstMip of Dst.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: Don't use this with Src == Dst, use UpdateMips instead!
Return to Contents


GENESISAPI geBoolean  GENESISCC geBitmap_ClearMips(geBitmap* Bmp);

This function clears/destroys all MIPs except the initial MIP from Bmp.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: Destroy all mips (except the first)! Use with care! This is not polite!
Return to Contents


GENESISAPI geBitmap* GENESISCC geBitmap_Create(int Width, int Height, int MipCount, gePixelFormat Format );

This function creates and returns a new geBitmap with the specified Width, Height, MipCount, pixel format Format.
Returns: the created geBitmap.
Return to Contents


GENESISAPI geBitmap* GENESISCC geBitmap_CreateFromFile(geVFile* F);

This function creates a new bitmap object from a file (BMP I presume).
Returns: the new geBitmap.
Return to Contents


GENESISAPI geBitmap* GENESISCC geBitmap_CreateFromFileName(const geVFile* BaseFS, const char * Name);

This function creates a new bitmap from the named file and file system.
Returns: the new geBitmap.
Return to Contents


GENESISAPI geBitmap* GENESISCC geBitmap_CreateFromInfo(const geBitmap_Info* pInfo);

This function creates a new blank bitmap object based on the properties in pInfo.
Returns: the new geBitmap.
Return to Contents


GENESISAPI void GENESISCC geBitmap_CreateRef(geBitmap* Bmp);

This function adds one to the reference count for Bmp.
Returns: nothing.
Return to Contents


GENESISAPI uint32 GENESISCC geBitmap_Debug_GetCount(void);

This function provides a count of the number of bitmap references still extant in the system (I think).  Basically at shutdown this should return 0 otherwise some bitmap is not being properly destroyed.  This API is only available in debug mode.
Returns: the number of bitmap references in existence.
Notes:
    from BITMAP.H:  assert this is zero before you shutdown !
Return to Contents


GENESISAPI uint32 GENESISCC geBitmap_Debug_GetRefs(void);

Added for Genesis3D v1.6
Notes:
    from BITMAP.H:  assert this is zero before you shutdown !
Return to Contents


GENESISAPI geBoolean  GENESISCC geBitmap_Destroy(geBitmap** Bmp);

This function decreases by one the reference count for Bmp.  If the reference count reaches zero all resources for the bitmap are cleaned up.
Returns: GE_TRUE if successful, GE_FALSE otherwise.
Notes:
    from BITMAP.H: returns whether Bmp was actually destroyed : not success/failure
Return to Contents


GENESISAPI geBitmap* GENESISCC geBitmap_GetAlpha(const geBitmap* Bmp);

This function returns a geBitmap with just the current alpha channel of Bmp.
Returns: the alpha channel bitmap.
Return to Contents



GENESISAPI geBoolean GENESISCC geBitmap_GetAverageColor(const geBitmap* Bmp, int * pR, int * pG, int * pB);

This function returns the average color for Bmp in (pR,pG,pB).
Returns: GE_TRUE if successful, GE_FALSE otherwise.
Notes:
    from BITMAP.H: Tells you the average color; computes it and caches it out.
Return to Contents


GENESISAPI void * GENESISCC geBitmap_GetBits(geBitmap* Bmp);

This function returns a pointer to the actual bits of Bmp which must be Locked.
Returns: the pointer to the bitmap data.
Notes:
    from BITMAP.H: works only on a Lock().
Return to Contents


GENESISAPI geBoolean  GENESISCC geBitmap_GetInfo(const geBitmap* Bmp, geBitmap_Info* Info, geBitmap_Info* SecondaryInfo);

This function returns the info for Bmp.  The Info/SecondaryInfo seems to have something to do with the driver.  If a driver is in use the Info is the Driver info and SecondaryInfo is the actual bitmap's info, otherwise Info is the bitmap's info.  If SecondaryInfo is BasetypesIndexed.htm - NULLNULL then SecondaryInfo will not be returned.
Returns: GE_TRUE if successful, GE_FALSE otherwise.
Notes:
    from BITMAP.H: LockForWrite returns data in Info's format.
Return to Contents


GENESISAPI geBitmap_Palette* GENESISCC geBitmap_GetPalette(const geBitmap* Bmp);

This function returns the palette for Bmp.
Returns: the geBitmap_Palette.
Return to Contents


GENESISAPI gePixelFormat GENESISCC geBitmap_GetPreferredFormat(const geBitmap* Bmp);

This function returns the gePixelFormat for Bmp.
Returns: the gePixelFormat.
Return to Contents


GENESISAPI geBitmap_StreamingStatus GENESISCC geBitmap_GetStreamingStatus(const geBitmap* Bmp);

Not implemented in v1.01 to v1.6.
Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_HasAlpha(const geBitmap* Bmp);

This function checks whether Bmp has any alpha and returns the result.
Returns: GE_TRUE if Bmp has alpha, GE_FALSE if not.
Notes:
    from BITMAP.H: returns true if bitmap has* any* type of alpha

Return to Contents


GENESISAPI int GENESISCC geBitmap_Height(const geBitmap* Bitmap);

This function returns the Height of Bitmap in pixels.
Returns: the Height of Bitmap.


 

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_LockForRead(const geBitmap* Bmp, geBitmap** Target, int MinimumMip, int MaximumMip, gePixelFormat Format, geBoolean RespectColorKey, uint32 ColorKey);

incomplete

This function locks the geBitmap Bmp for reading.  I'm not too sure about this one.
Notes:
    from BITMAP.H: A non-exclusive lock. Not really const, stores lock-count, but* data* is const. Will do a format conversion!
Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_LockForReadNative(const geBitmap* Bmp, geBitmap** Target, int MinimumMip, int MaximumMip);

incomplete

This function locks the geBitmap Bmp for reading.  Again, I don't really get this.
Notes:
    from BITMAP.H: Lock for read in a format that gaurantee no conversions. Then do GetInfo on the locks to see what you have!
Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_LockForWrite(geBitmap* Bmp, geBitmap** Target, int MinimumMip, int MaximumMip);

incomplete

Once again, I'm a bit clueless.  I think maybe Target returns the geBitmap that is edittable.  But...
Notes:
    from BITMAP.H: an exclusive lock
Return to Contents


GENESISAPI geBoolean  GENESISCC geBitmap_LockForWriteFormat(geBitmap* Bmp, geBitmap** Target, int MinimumMip, int MaximumMip, gePixelFormat Format);

incomplete

Notes:
    from BITMAP.H: Format must be one of the two returned in GetInfo !!

Return to Contents

 

GENESISAPI uint32 GENESISCC geBitmap_MipBytes(const geBitmap* Bitmap, int mip);

This function returns the number of bytes in the specified mip of Bitmap.
Returns: the result.
Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_Copy(const geBitmap_Palette* Src, geBitmap_Palette* Target);

This function copies the palette of Src to Target.
Returns: GE_TRUE on success, GE_FALSE otherwise.
 
Return to Contents


GENESISAPI geBitmap_Palette* GENESISCC geBitmap_Palette_Create(gePixelFormat Format, int Size);

This function creates a geBitmap_Palette object with the specified pixel format Format and Size entries.
Returns: the created geBitmap_Palette.

Return to Contents


GENESISAPI geBitmap_Palette* GENESISCC geBitmap_Palette_CreateCopy(const geBitmap_Palette* Palette);

This function creates a new geBitmap_Palette identical to Palette.
Returns: the copied geBitmap_Palette.
Return to Contents


GENESISAPI geBitmap_Palette* GENESISCC geBitmap_Palette_CreateFromBitmap(geBitmap* Bmp, geBoolean Slow);

This function generates a palette from the given geBitmap.  If Slow == GE_TRUE it does a slower, higher-quality version.
Returns: the newly created geBitmap_Palette.
Notes:
    from BITMAP.H: Does GetPalette, and if NULL, then it create an optimal palette for a non-palettized bitmap (this is a create, you must destroy later!) Put Slow == TRUE for higher quality & slower.
Return to Contents


GENESISAPI geBitmap_Palette* GENESISCC geBitmap_Palette_CreateFromFile(geVFile* F);

This function reads the header date of the bitmap file F and creates an empty palette with the same stats.
Returns: the created geBitmap_Palette.
Return to Contents


GENESISAPI geBoolean  GENESISCC geBitmap_Palette_CreateRef(geBitmap_Palette* Palette);

This function increases the reference count of the geBitmap_Palette by one.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_Destroy(geBitmap_Palette** ppPalette);

This function destroys (decreases reference count by one) the geBitmap_Palette freeing up resources if possible.
Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_GetData(const geBitmap_Palette* P, void * Into, gePixelFormat Format, int Colors);

This function creates a copy of the palette data of P at Format pixelformat and Colors colordepth and returns the pointer in Into.
Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_GetEntry(const geBitmap_Palette* P, int Color, uint32* Pixel);

This function returns entry Color of P in Pixel.  All of the Get/Set functions handle locking for you which makes them slow.  Be careful.
Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_GetEntryColor(const geBitmap_Palette* P, int Color, int * R, int * G, int * B, int * A);

This function returns entry Color of palette P in (R,G,B,A).  All of the Get/Set functions handle locking for you which makes them slow.  Be careful.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: Set/Get does Lock/Unlock for you ; these are slow! do not use these to work on all the colors!

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_GetInfo(const geBitmap_Palette* P, geBitmap_Info* Into);

This function returns the info from the palette P.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: get the info as if it were a bitmap; Into-Height == 1

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_Lock(geBitmap_Palette* Palette, void ** pBits, gePixelFormat* pFormat, int * pSize);

incomplete

This function locks the palette.  I still don't get how these work, I'll have to find some examples eventually.
Notes:
    from BITMAP.H: pFormat & pSize are optional

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_SetData(geBitmap_Palette* P, const void * From, gePixelFormat Format, int Colors);

This function sets the palette data of P from From for pixelformat Format and colordepth Colors.  This handles lock/unlock for you.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H:  does Lock/UnLock for you. From and Into are arrays of Colors*gePixelFormat_BytesPerPel bytes

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_SetEntry(geBitmap_Palette* P, int Color, uint32 Pixel);

This function sets entry Color of palette P to Pixel.  It handle lock/unlock for you.
Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_SetEntryColor(geBitmap_Palette* P, int Color, int R, int G, int B, int A);

This function sets entry Color of palette P to (R,G,B,A).  It handles lock/unlock for you.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_SetFormat(geBitmap_Palette* Palette, gePixelFormat Format);

incomplete

This function sets the gePixelFormat of Palette to Format. This function doesn't appear to do any lock/unlock for you.  Is it necessary?

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_SortColors(geBitmap_Palette* P, geBoolean Slower);

It doesn't appear that this is currently implemented.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_UnLock(geBitmap_Palette* Palette);

This function unlocks Palette.  Details still elude me.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: Palette unlock does NOT notify the bitmap that the palette has changed. Call Bitmap_SetPalette() with the same palette pointer to tell the bitmap that it must to some processing (don't worry, it won't duplicate it or copy it onto itself)

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_Palette_WriteToFile(const geBitmap_Palette* Palette, geVFile* F);

This function writes the geBitmap_Palette Palette to file F.  Is this just raw data (uint32s)?
Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_RefreshMips(geBitmap* Bmp);

This function rebuilds the MIPs of the geBitmap Bmp from the base data.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: rebuilds mips;* tries* to be smart & not overwrite manually-fixed mips. RefreshMips does* not* build mips that don't exist

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_SetAlpha(geBitmap* Bmp, const geBitmap* AlphaBmp);

incomplete

This function sets the alpha layer of Bmp to AlphaBmp.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: We Ref the AlphaBmp, so you may destroy it after calling Set(). it may be BasetypesIndexed.htm - NULLNULL. there's only one Alpha per bitmap (for the top Mip) right now.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_SetColorKey(geBitmap* Bmp, geBoolean HasColorKey, uint32 ColorKey, geBoolean Smart);

This function sets the color key of Bmp to ColorKey.  It sets the HasColorKey element of Bmp to HasColorKey.  I don't really follow the Smart arg.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.h: SetColorKey discards old colorkey information! does not do a conversion (changes the colorkey in the current data) if 'Smart' is on, we don't set HasColorKey to true unless it is actually used!

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_SetFormat(geBitmap* Bmp, gePixelFormat NewFormat, geBoolean RespectColorKey, uint32 ColorKey, const geBitmap_Palette* Palette);

This function sets Bmp's format information to that specified doing any necessary conversions.  If the new format is palettized in Palette == BasetypesIndexed.htm - NULLNULL, the new palette is returned in Palette.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H:  _SetFormat may cause you to lose color information! SetFormat does a conversion! If NewFormat is palettized and Palette is BasetypesIndexed.htm - NULLNULL, we create a palette for the bitmap!

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_SetFormatMin(geBitmap* Bmp, gePixelFormat NewFormat);

This function sets the format of Bmp to Newformat but maintains colorkey and palette.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: the Min version keeps colorkey & palette from the old format

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_SetGammaCorrection(geBitmap* Bmp, geFloat Gamma, geBoolean Apply);

This function sets the Gamma level of Bmp if Apply == GE_TRUE.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: This Gamma does not change the* original* (system/secondary) bits, it only affects the appearance when drawn. Note: if you write to the gamma corrected bits, you must gamma correct manually if you wish to fit in smoothly with the previous data. Warning : if you use this function with many different gammas, performance will suffer! use one global gamma for all bitmaps!  try to let the engine manage gamma for you, via geEngine_SetGamma !

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_SetMipCount(geBitmap* Bmp , int Count);

This function changes to total number of MIPs of Bmp to Count, destroying or creating as necesary.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: creates or destroys to match the new count

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_SetPalette(geBitmap* Bmp, const geBitmap_Palette* Palette);

This function sets the palette of Bmp to Palette.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: _SetPal tries to _CreateRef your Palette, so no copy occurs & palettes may be shared you may _Destroy() palette after using it to set (though its bits may not be freed) (hence Palette is* not* const) Warning : SetPalette on any mip changes the palette of ALL mips ! see Palette note at _UnLock _SetPal destroys the bitmap's original palette and refs the new one, so if you setpal with the bitmap's palette, there is no net change in ref counts (good!)

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_SetPreferredFormat(geBitmap* Bmp, gePixelFormat Format);

This function sets the pixelformat of Bmp to Format.
Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_UnLock(geBitmap* Bmp);

This function unlocks the bitmap Bmp.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: must be done on All locked mips

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_UnLockArray(geBitmap** Locks, int Size);

This function unlocks and array Size bitmaps.
Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_UpdateMips(geBitmap* Bmp, int SourceMip, int TargetMip);

This function recreates TargetMip from SourceMip in Bmp.
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: will create the target if it doesn't exist; will overwrite manually-fixed mips!

Return to Contents


GENESISAPI int GENESISCC geBitmap_Width(const geBitmap* Bitmap);

This function returns the width of Bitmap.
Returns: the result.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_WriteToFile(const geBitmap* Bmp, geVFile* F );

This function writes Bmp to the file F (in .bmp format?).
Returns: GE_TRUE on success, GE_FALSE otherwise.

Return to Contents


GENESISAPI geBoolean GENESISCC geBitmap_WriteToFileName(const geBitmap* Bmp, const geVFile* BaseFS, const char * Name);

This function writes Bmp to the file specified by BaseFS and Name.  (.bmp?)
Returns: GE_TRUE on success, GE_FALSE otherwise.
Notes:
    from BITMAP.H: BaseFS is not really const if it is a virtual file; it* is* const if it is a dos directory.

Notes:
    from BITMAP.H:  If Bitmap is a lock for read, functions that modify it return failure. If Bitmap is a lock for write, functions that modify it attempt to modify the owner of the lock. warning : if you lock multiple mips for write, and then modify one of the mips (such as via SetPalette) it may affect the owner and all sibling mips!  Doing different SetPalettes with different palettes on different locked mips has undefined behavior!
 
Return to Contents

extern geBoolean geBitmap_BlitData(const geBitmap_Info* SrcInfo, const void * SrcData, const geBitmap* SrcBmp, geBitmap_Info* DstInfo, void * DstData, const geBitmap* DstBmp, int SizeX, int SizeY);

(Source file: ...\genesis3d\OpenSource\Source\Bitmap\bitmap_blitdata.h)

PURPOSE: Does all format conversions

  
Return to Contents

extern geBoolean geBitmap_Gamma_Apply(geBitmap* Bitmap, geBoolean Invert);

(Source file: ...\genesis3d\OpenSource\Source\Bitmap\bitmap_gamma.h)

PURPOSE: Fast Gamma correction routines for various pixel formats

 

Return to Contents

Notes:

From bitmap.h:

* if Bitmap is a lock for read, functions that modify it return failure
* if Bitmap is a lock for write, functions that modify it attempt to
* modify the owner of the lock
*
* warning : if you lock multiple mips for write, and then modify one of the mips
* (such as via SetPalette) it may affect the owner and all sibling mips!
* doing different SetPalettes with different palettes on different locked mips
* has undefined behavior!

Return to Contents

Tutorial

/************************************************************************

 

A brief tutorial on the Bitmap system, by Charles Bloom, cbloom@wildtangent.com

 

The Bitmap is a smart wrapper for complex functionality. You give it hints to the opaque Bitmap object, and it tries its best to follow those hints, but it may not always do so. The Bitmap is the owner of its bits; you must Lock the bitmap to get permission to touch those bits, and UnLock to tell the bitmap you are done. The format may change between two Locks. Bitmaps can also be multiply owned, so you should account for the fact that others may touch your bitmap between your uses.

The Bitmap contains one or two pixel-sets representing an image. The "primary" is a fast-blitting version of the image, and the "secondary" is a storage version (eventually wavelet compressed) which can be used to rebuild the primary if it is freed or damaged. Both carry a generalized format.

Let's do an example. I want to load a bitmap, set it up for drawing with the genesis Engine, and then blit some interactive stuff into it.

******** 

//-----------------------------------------------------------------------------
void Init(geEngine* Engine);
void Shutdown(void);
void Draw(void);
void DrawPolite(void);
static geBitmap* myBM = NULL; static geEngine* myEngine = NULL;
void Init(geEngine* Engine)
{
  geBoolean success;
  geBitmap_Info Info;
  myEngine = Engine; // this is not looked well upon; for ease of demonstration only! assert(Engine); myBM = geBitmap_CreateFromFileName(NULL,"mybitmap.bmp"); // CreateFromFile can load windows BMP files, or custom GeBm files. assert(myBM); 
  // get the main info; I don't care about the secondary, so leave it NULL
  success = geBitmap_GetInfo(myBM,&Info,NULL);
  assert(success);
  // make sure I loaded a bitmap in the format I understand !
  if ( Info.Format == GE_PIXELFORMAT_8BIT_PAL )
  {
    // I want palette index 255 to act as transparency, so I must use SetColorKey
    success = geBitmap_SetColorKey(myBM,GE_TRUE,255);
    assert(success);
    // just for fun, let's modify the palette:
    if (1)
    {
      geBitmap_Palette* Pal;
      // get the palette ; I don't care if its primary or secondary, so
      /// I don't use the Info.Palette field
      Pal = geBitmap_GetPalette(myBM);
      assert(Pal);
      // I'm only fiddling one entry, so don't bother with a full Lock() UnLock()
      // sequence on the palette
      // make palette index zero bright red; we use alpha = 255 for opaque
      success = geBitmap_Palette_SetEntryColor(Pal,0,255,0,0,255);
      assert(success);
      // tell the bitmap system you've changed the palette; this function
      // is smart enough to not do unecessary copies or whatever.
      success = geBitmap_SetPalette(myBM,Pal);
      assert(success);
    }
  } else {
    // otherwise, treat black as transparent, in whatever format I have
    success = geBitmap_SetColorKey(myBM,GE_TRUE, gePixelFormat_ComposePixel(Info.Format,0,0,0,0));
    assert(success);
  } 
  // note that I did NOT use SetFormat. SetFormat may do a conversion, and since the original
  // bitmap was created without colorkey, it would have been converted to a new format but
  // kept its property of having no colorkey!
  // (SetFormat will fiddle the bits and whatever way necessary to keep bitmaps as visually similar
  // as possible)
  // I want to fiddle the fast format in 565 later, so cue the bitmap to try to give me that format.
  success = geBitmap_SetPreferredFormat(myBM,GE_PIXELFORMAT_16BIT_565_RGB);
  assert(success);
  // Add it to the engine so it can be used for drawing.
  success = geEngine_AddBitmap(myEngine,myBM);
  assert(success);
}

 

void Shutdown(void)
{
  geBoolean WasDestroyed;
  assert(myBM);
  // clean up
  geEngine_RemoveBitmap(myEngine,myBM);
  WasDestroyed = geBitmap_Destroy(&myBM);
  // someone else might have done _CreateRef on our bitmap,
  // so we can't be sure it's actually destroyed.
  // this code is still ready to be run again with a new call to Init()
  //assert(WasDestroyed);
  myBM = NULL;
  myEngine = NULL;
}

 

void Draw(void)
{
  geBitmap* Lock;
  geBoolean success; 
  geBitmap_Info Info;
  uint16 *bits,*bptr; 
  int x,y; 
  // lets fiddle the bits. 
  // we need to lock the bitmap for write. 
  // LockForWrite is an exclusive lock, unlike LockForRead which is non-blocking
  // request our favorite format, and only lock Mip 0 (the full size bitmap) 
  success = geBitmap_LockForWriteFormat(myBM,&Lock,0,0,GE_PIXELFORMAT_16BIT_565_RGB);
  if ( ! success )
  {
    // well, we tried to be nice; if we were very polite, we would do a LockForWrite
    // here, and try to fiddle the bits in whatever format we got; However, we aren't
    // that polite, so we just do a _SetFormat
    //
    // note that we are destroying the original bitmap by changing its format
    // we should only do this if we are going to draw into the bitmap
    success = geBitmap_SetFormat(myBM,GE_PIXELFORMAT_16BIT_565_RGB,GE_TRUE,0,NULL);
    assert(success);
    // now we should be able to get the bits we want, *but* they may not be the
    // primary (fast) format; oh well, it's the best we can do...
    // (if you must have the fastest bits, then use only _LockForWrite, never LockForWriteFormat,
    // which might have to do a conversion)
    success = geBitmap_LockForWriteFormat(myBM,&Lock,0,0,GE_PIXELFORMAT_16BIT_565_RGB);
    assert(success);
  }
  // now Lock is our bitmap in 565
  // we do a GetInfo because the Lock's info could be different than
  // the original bitmap's (particularly the Palette & the Stride)

 

  success = geBitmap_GetInfo(Lock,&Info,NULL);
  assert(success);
  // you can only call _GetBits on a locked bitmap
  bits = geBitmap_GetBits(Lock);
  assert( bits );
  bptr = bits;
  for(y=0; y < Info.Height; y++)
  {
    for(x=0; x < Info.Width; x++)
    {
      uint16 R,G,B; 
      // make a silly 565 gradient
      R = x & 0x1F; 
      G = x & 0x3F; 
      B = y & 0x1F; 
      *bptr++ = (R<<11) + (G<<5) + B; 
    }
    // note that bptr is a word pointer, and Stride is in pixels : 
    bptr += Info.Stride - Info.Width; 
  }
  bits = bptr = NULL; 
  // you call Unlock on all the mips you locked - not on the original bitmap! 
  success = geBitmap_UnLock(Lock);
  assert(success);
  // now, we only fiddled the full-size Mip, and there might be more,
  // so lets percolate the changes into the smaller mips:
  success = geBitmap_RefreshMips(myBM);
  assert(success);
  // a null rect means use the whole bitmap;
  // Engine_DrawBitmap blits a 2d decal to the framebuffer (fast)
  success = geEngine_DrawBitmap(myEngine,myBM,NULL,0,0);
  assert(success);
}

 

void DrawPolite(void)
{
  geBitmap* Lock;
  geBoolean success; 
  geBitmap_Info Info;
  void* bits;
  int x,y;
  // this function does the same thing as Draw() , but is more polite
  // lock in the fastest format (whatever it is)
  // because we did SetPreferred, this should be 565_RGB, but might not be
  success = geBitmap_LockForWrite(myBM,&Lock,0,0);
  assert(success);
  success = geBitmap_GetInfo(Lock,&Info,NULL);
  assert(success);
  bits = geBitmap_GetBits(Lock);
  assert( bits );
  if ( Info.Format == GE_PIXELFORMAT_16BIT_565_RGB )
  {
    uint16* wptr;
    // our favorite format
    wptr = bits;
    for(y=0; y < Info.Height; y++)
    {
      for(x=0; x < Info.Width; x++)
      {
        uint16 R,G,B; 
        // make a silly 565 gradient
        R = x & 0x1F; 
        G = x & 0x3F; 
        B = y & 0x1F; 
        *wptr++ = (R<<11) + (G<<5) + B; 
      }
      wptr += Info.Stride - Info.Width; 
    }
  } else {
    uint8* bptr;
    // oh well, do our best
    // bitmaps must have had a good reason to not give us the format we preferred,
    bptr = bits;
    for(y=0; y < Info.Height; y++)
    {
      for(x=0; x < Info.Width; x++)
      {
        uint32 R,G,B; 
        // put a color in any format
        R = (x & 0x1F)<<3; 
        G = (x & 0x3F)<<2; 
        B = (y & 0x1F)<<3; 
        // we use alpha of 255 for opaque
        gePixelFormat_PutColor(Info.Format,&bptr,R,G,B,255);
      }
      bptr += (Info.Stride - Info.Width) * gePixelFormat_BytesPerPel(Info.Format);
    }
  }
  bits = NULL;
  // same as before:
  success = geBitmap_UnLock(Lock);
  assert(success);
  success = geBitmap_RefreshMips(myBM);
  assert(success);
  success = geEngine_DrawBitmap(myEngine,myBM,NULL,0,0);
  assert(success);
}

 

// end tutorial on the Bitmap system
//-----------------------------------------------------------------------------
// }

 

/***********************************************************************************/

 

#endif

 

Return to Contents