ineffable's unofficial JET3D API Reference

jeBitmap

Last Updated 3/8/2000.

Types:

jeBitmap;

jeBitmap_Palette;

jeBitmap_Info;

typedef struct jeBitmap_Info{
    int                Width;
    int                Height;
    int                Stride; // stride is in *pixels* ; it is the step to the next line : Stride >= Width
    jePixelFormat      Format;
    int                MinimumMip; //*including* minimumMip == 0 often
    int                MaximumMip; //*including* maximumMip == nummips-1
    jeBoolean          HasColorKey;
    uint32             ColorKey; // meaningless unless HasColorKey ; the ColorKey is a Pixel in Format
    jeBitmap_Palette* Palette;
} jeBitmap_Info;

Constants:

JE_BITMAP_STREAMING_

typedef enum {
    JE_BITMAP_STREAMING_ERROR=0,
    JE_BITMAP_STREAMING_NOT,
    JE_BITMAP_STREAMING_STARTED,
    JE_BITMAP_STREAMING_IDLE,
    JE_BITMAP_STREAMING_CHANGED,
    JE_BITMAP_STREAMING_DATADONE,
    JE_BITMAP_STREAMING_DONE,
} jeBitmap_StreamingStatus;

Functions:

JETAPI geBoolean JETCC jeBitmap_Blit(const jeBitmap *Src, int SrcPositionX, int SrcPositionY, jeBitmap *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: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_BlitBestMip(const jeBitmap* Src, jeBitmap* Dst);

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

JETAPI jeBoolean JETCC jeBitmap_BlitBitmap(const jeBitmap * Src, jeBitmap * Dst);

This function blits the best mip in bitmap Src into the best mip of Dst.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_BlitMip(const jeBitmap* Src, int SrcMip, jeBitmap* Dst, int DstMip);

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

JETAPI jeBoolean JETCC jeBitmap_ClearMips(jeBitmap *Bmp);

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

JETAPI jeBitmap* JETCC jeBitmap_Create(int Width, int Height, int MipCount, jePixelFormat Format );

This function creates and returns a new, empty jeBitmap with the specified Width, Height, MipCount, and pixel format Format.
Returns: the created jeBitmap.

JETAPI jeBitmap* JETCC jeBitmap_CreateCopy(const jeBitmap* Src);

This function creates a new jeBitmap object identical to Src and returns it.
Returns: the newly created jeBitmap object.

JETAPI jeBitmap* JETCC jeBitmap_CreateFromFile(jeVFile *F);

This function creates a new bitmap object from a file. The file must have been created using an engine function such as geBitmap_WriteToFile().
Returns: the new jeBitmap.

JETAPI jeBitmap* JETCC jeBitmap_CreateFromFile2(jeVFile* VFile, jeVFile* ResourceBaseFS, jePtrMgr* PtrMgr);

This function creates a new jeBitmap object from a file. This works much like _CreateFromFile except that it makes use of a jePtrMgr object and allows specification of the base of a virtual file system in ResourceBaseFS.
Returns: the jeBitmap.

JETAPI jeBitmap* JETCC jeBitmap_CreateFromFileName(const jeVFile* BaseFS, const char* Name);

This function creates a new bitmap from the named file and file system. The file must have been created using an engine function such as geBitmap_WriteToFile().
Returns: the new jeBitmap.

JETAPI jeBitmap* JETCC jeBitmap_CreateFromFileName2(const jeVFile *BaseFS, const char* Name, jePtrMgr *PtrMgr);

This function creates a new bitmap from the named file and file system. It works much like _CreateFileFromName with the exception that it makes use of a jePtrMgr object.
Returns: the new jeBitmap.

JETAPI jeBitmap* JETCC jeBitmap_CreateFromInfo(const jeBitmap_Info *pInfo);

This function creates a new blank bitmap object based on the properties in pInfo.
Returns: the new jeBitmap.

JETAPI void JETCC jeBitmap_CreateRef(jeBitmap *Bmp);

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

JETAPI uint32 JETCC jeBitmap_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!

JETAPI jeBoolean JETCC jeBitmap_Destroy(jeBitmap **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: JE_TRUE if Bmp is deleted, JE_FALSE if the reference count is greater than zero after subtracting one.
Notes:
from BITMAP.H: returns whether Bmp was actually destroyed : not success/failure

JETAPI jeBitmap* JETCC jeBitmap_GetAlpha(const jeBitmap *Bmp);

This function returns a jeBitmap with just the current alpha channel of Bmp.
Returns: the alpha channel bitmap.

JETAPI jeBoolean JETCC jeBitmap_GetAverageColor(const jeBitmap* Bmp, int* pR, int* pG, int* pB);

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

JETAPI void *JETCC jeBitmap_GetBits(jeBitmap *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().

JETAPI jeBoolean JETCC jeBitmap_GetInfo(const jeBitmap* Bmp, jeBitmap_Info* Info, jeBitmap_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: JE_TRUE if successful, JE_FALSE otherwise.
Notes:
from BITMAP.H: LockForWrite returns data in Info's format.

JETAPI jeBitmap_Palette* JETCC jeBitmap_GetPalette(const jeBitmap *Bmp);

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

JETAPI jeBoolean JETCC jeBitmap_GetPersistableName(const jeBitmap* Bmp, jeVFile** pBaseFS, char** pName);

I don't know about this yet.

JETAPI jePixelFormat JETCC jeBitmap_GetPreferredFormat(const jeBitmap *Bmp);

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

JETAPI jeBitmap_StreamingStatus JETCC jeBitmap_GetStreamingStatus(const jeBitmap *Bmp);

This function returns the current jeBitmap_StreamingStatus for jeBitmap Bmp.
Returns: the jeBitmap_StreamingStatus.

JETAPI jeBoolean JETCC jeBitmap_HasAlpha(const jeBitmap * Bmp);

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

JETAPI int JETCC jeBitmap_Height(const jeBitmap *Bitmap);

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

JETAPI jeBoolean JETCC jeBitmap_LockForRead(const jeBitmap* Bmp, jeBitmap** Target, int MinimumMip, int MaximumMip, jePixelFormat Format, jeBoolean RespectColorKey, uint32 ColorKey);

incomplete

This function locks the jeBitmap 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!

JETAPI jeBoolean JETCC jeBitmap_LockForReadNative(const jeBitmap* Bmp, jeBitmap** Target, int MinimumMip, int MaximumMip);

incomplete

This function locks the jeBitmap 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!

JETAPI jeBoolean JETCC jeBitmap_LockForWrite(jeBitmap* Bmp, jeBitmap** Target, int MinimumMip, int MaximumMip);

incomplete

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

JETAPI jeBoolean JETCC jeBitmap_LockForWriteFormat(jeBitmap* Bmp, jeBitmap** Target, int MinimumMip, int MaximumMip, jePixelFormat Format);

incomplete

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

JETAPI uint32 JETCC jeBitmap_MipBytes(const jeBitmap* Bitmap, int mip);

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

JETAPI jeBoolean JETCC jeBitmap_Palette_Copy(const jeBitmap_Palette* Src, jeBitmap_Palette* Target);

This function copies the contents of palette Src to Target. Target must be an existing palette with the same format and size as Src.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBitmap_Palette* JETCC jeBitmap_Palette_Create(jePixelFormat Format, int Size);

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

JETAPI jeBitmap_Palette* JETCC jeBitmap_Palette_CreateCopy(const jeBitmap_Palette* Palette);

This function creates a new jeBitmap_Palette identical to Palette.
Returns: the copied jeBitmap_Palette.

JETAPI jeBitmap_Palette* JETCC jeBitmap_Palette_CreateFromBitmap(jeBitmap* Bmp, jeBoolean Slow);

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

JETAPI jeBitmap_Palette* JETCC jeBitmap_Palette_CreateFromFile(jeVFile* F);

This function reads jePalette file F and creates a new jePalette with its contents.
Returns: the created jeBitmap_Palette.

JETAPI jeBoolean JETCC jeBitmap_Palette_CreateRef(jeBitmap_Palette* Palette);

This function increases the reference count of the jeBitmap_Palette Palette by one.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_Palette_Destroy(jeBitmap_Palette** ppPalette);

This function destroys (decreases reference count by one) the jeBitmap_Palette ppPalette freeing up resources if possible.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_Palette_GetData(const jeBitmap_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: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_Palette_GetEntry(const jeBitmap_Palette* P, int Color, uint32* Pixel);

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

JETAPI jeBoolean JETCC jeBitmap_Palette_GetEntryColor(const jeBitmap_Palette* P, int Color, int* R, int* G, int* B, int* A);

This function returns entry Color of jeBitmap_Palette P in (R,G,B,A). All of the Get/Set functions handle locking for you which makes them slow. Be careful.
Returns: JE_TRUE on success, JE_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!

JETAPI jeBoolean JETCC jeBitmap_Palette_GetInfo(const jeBitmap_Palette* P, jeBitmap_Info* Into);

This function returns the info from the palette P in Into. Info->Height will be returned as 1.
Returns: JE_TRUE on success, JE_FALSE otherwise.
Notes:
from BITMAP.H: get the info as if it were a bitmap; Into->Height == 1

JETAPI jeBoolean JETCC jeBitmap_Palette_Lock(jeBitmap_Palette* Palette, void** pBits, jePixelFormat* 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.
Returns: JE_TRUE on success, JE_FALSE otherwise.
Notes:
from BITMAP.H: pFormat & pSize are optional

JETAPI jeBoolean JETCC jeBitmap_Palette_SetData(jeBitmap_Palette* P, const void* From, jePixelFormat 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: JE_TRUE on success, JE_FALSE otherwise.
Notes:
from BITMAP.H: does Lock/UnLock for you. From and Into are arrays of Colors*jePixelFormat_BytesPerPel bytes

JETAPI jeBoolean JETCC jeBitmap_Palette_SetEntry(jeBitmap_Palette* P, int Color, uint32 Pixel);

This function sets entry Color of palette P to Pixel. It handles lock/unlock for you.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_Palette_SetEntryColor(jeBitmap_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: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_Palette_SetFormat(jeBitmap_Palette* Palette, jePixelFormat Format);

incomplete

This function sets the jePixelFormat of Palette to Format. This function doesn't appear to do any lock/unlock for you. Is it necessary?
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_Palette_SortColors(jeBitmap_Palette* P, jeBoolean Slower);

This function sorts jeBitmap_Palette P. If Slower is JE_TRUE a slower, higher quality sort is performed.
Returns: JE_TRUE on success, JE_FALSE otherwise

JETAPI jeBoolean JETCC jeBitmap_Palette_UnLock(jeBitmap_Palette* Palette);

This function unlocks Palette. Details still elude me.
Returns: JE_TRUE on success, JE_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)

JETAPI jeBoolean JETCC jeBitmap_Palette_WriteToFile(const jeBitmap_Palette* Palette, jeVFile* F);

This function writes the jeBitmap_Palette Palette to file F.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_RefreshMips(jeBitmap *Bmp);

This function rebuilds the MIPs of the jeBitmap Bmp from the base data.
Returns: JE_TRUE on success, JE_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

JETAPI jeBoolean JETCC jeBitmap_SetAlpha(jeBitmap* Bmp, const jeBitmap* AlphaBmp);

This function sets the alpha layer of Bmp to AlphaBmp.
Returns: JE_TRUE on success, JE_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.

JETAPI jeBoolean JETCC jeBitmap_SetColorKey(jeBitmap* Bmp, jeBoolean HasColorKey, uint32 ColorKey, jeBoolean Smart);

This function sets the color key of Bmp to ColorKey. It sets the HasColorKey element of Bmp to HasColorKey. If Smart == JE_TRUE, the ColorKey is only set if the current format of Bmp utilizes it; otherwise it is set without any test.
Returns: JE_TRUE on success, JE_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!

JETAPI jeBoolean JETCC jeBitmap_SetCompressionOptions(jeBitmap* Bmp, int CompressionLevel, jeBoolean NeedMips, jeFloat ratio);

This function sets the compression options for jeBitmap Bmp. CompressionLevel is a value from 0 to 10 where 0 = least compression, fastest compression time and 10 = most compression, slower compression time. NeedMips indicates that mips should be created during decompress (?). ratio specifies the minimum desired compression ratio and is specified by (Image Size In) / (Image Size Out), in other words the higher the number the more compression is desired.
Returns: JE_TRUE on success, JE_FALSE otherwise.
Notes:
CompressionOptions to be used in any later compression (not written to file). level is 0-10, for 0 = fastest, 10 = most compression. NeedMips tells the coder whether to provide for fast mip creation in decompression. ratio is the *minimum* compression ratio (In_Len/Out_Len); higher ratios create loss

JETAPI jeBoolean JETCC jeBitmap_SetCompressionOptionsExpert(jeBitmap* Bmp, jeFloat Ratio, int TransformN, int CoderN, jeBoolean TransposeLHs, jeBoolean Block);

This function sets the compression options for jeBitmap Bmp utilizing an expert level interface in relation to _SetCompressionOptions. I don't know what the other params are for at this time.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_SetFormat(jeBitmap* Bmp, jePixelFormat NewFormat, jeBoolean RespectColorKey, uint32 ColorKey, const jeBitmap_Palette* Palette);

This function sets Bmp's format information to that specified doing any necessary conversions. If the new format is palettized and Palette == NULL, the new palette is returned in Palette.
Returns: JE_TRUE on success, JE_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!

JETAPI jeBoolean JETCC jeBitmap_SetFormatMin(jeBitmap* Bmp, jePixelFormat NewFormat);

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

JETAPI jeBoolean JETCC jeBitmap_SetGammaCorrection(jeBitmap* Bmp, jeFloat Gamma, jeBoolean Apply);

This function sets the Gamma level of Bmp if Apply == GE_TRUE.
Returns: JE_TRUE on success, JE_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 !

JETAPI jeBoolean JETCC jeBitmap_SetMipCount(jeBitmap* Bmp, int Count);

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

JETAPI jeBoolean JETCC jeBitmap_SetPalette(jeBitmap* Bmp, const jeBitmap_Palette* Palette);

This function sets the palette of Bmp to Palette.
Returns: JE_TRUE on success, JE_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!)

JETAPI jeBoolean JETCC jeBitmap_SetPreferredFormat(jeBitmap* Bmp, jePixelFormat Format);

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

JETAPI jeBoolean JETCC jeBitmap_UnLock(jeBitmap *Bmp);

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

JETAPI jeBoolean JETCC jeBitmap_UnLockArray(jeBitmap** Locks, int Size);

This function unlocks an array of Size bitmaps.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_UpdateMips(jeBitmap *Bmp, int SourceMip, int TargetMip);

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

JETAPI int JETCC jeBitmap_Width(const jeBitmap* Bitmap);

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

JETAPI jeBoolean JETCC jeBitmap_WriteToFile(const jeBitmap* Bmp, jeVFile* F );

This function writes Bmp to the file F in a proprietary format.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_WriteToFile2(const jeBitmap* Bmp, jeVFile *VFile, jePtrMgr *PtrMgr);

This function writes Bmp to the file VFile in a propietary format. It differs from _WriteToFile in that it make use of a jePtrMgr.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeBitmap_WriteToFileName(const jeBitmap* Bmp, const geVFile* BaseFS, const char* Name);

This function writes Bmp to the file specified by BaseFS and Name.
Returns: JE_TRUE on success, JE_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!