ineffable's unofficial Genesis 3D v1.01 API Reference

geBitmap

Types:

geBitmap;

geBitmap_Palette;

geBitmap_Info;

typedef struct geBitmap_Info{
    int      Width;
    int      Height;
    int      Stride; // stride is in *pixels* ; it is 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;

Constants:

GE_BITMAP_STREAMING_

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;

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.

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

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?

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!

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!

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.

GENESISAPI geBitmap * GENESISCC geBitmap_CreateFromFile(geVFile *F);

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

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.

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.

GENESISAPI void GENESISCC geBitmap_CreateRef(geBitmap *Bmp);

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

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 !

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

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.

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.

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().

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 NULL 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.

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

This function returns the palette for Bmp.
Returns: the geBitmap_Palette.

GENESISAPI gePixelFormat GENESISCC geBitmap_GetPreferredFormat(const geBitmap *Bmp);

This function returns the gePixelFormat for Bmp.
Returns: the gePixelFormat.

GENESISAPI geBitmap_StreamingStatus GENESISCC geBitmap_GetStreamingStatus(const geBitmap *Bmp);

Not implemented in v1.01.

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

GENESISAPI int GENESISCC geBitmap_Height(const geBitmap *Bitmap);

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

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!

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!

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

incomplete

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

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 !!

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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!

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

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

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

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.

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.

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?

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

It doesn't appear that this is currently implemented.

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)

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.

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

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 NULL. there's only one Alpha per bitmap (for the top Mip) right now.

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!

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 == NULL, 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 NULL, we create a palette for the bitmap!

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

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 !

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

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!)

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.

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

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

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

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!

GENESISAPI int GENESISCC geBitmap_Width(const geBitmap *Bitmap);

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

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.

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!