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

jeEngine

Last Updated May 4, 2000

Types

jeEngine

This object represents the rendering engine. It does all the work of working with the jeDriver to render the world, object, and other graphics to the video display.

Constants

jeEngine_BitmapType

This is an enumerated type used to designate the way a bitmap should be used during rendering.
typedef enum {
JE_ENGINE_BITMAP_TYPE_2D,
JE_ENGINE_BITMAP_TYPE_3D
} jeEngineBitmapType;

jeEngine_FrameState

This is an enumerated type used to represent the current rendering state of the engine as returned by jeEngine_GetFrameState.
typedef enum {
FrameState_None = 0,
FrameState_Begin
} jeEngine_FrameState;

Functions:

JETAPI jeBoolean jeEngine_Activate(jeEngine* Engine, jeBoolean bActive);

incomplete

This seems to have something to do with whether the application is the current Active application. If the application has been moved to the background, this would seem to restore it to the foreground and take care of all necessary details. This is primarily implemented by the driver and therefore functionality may vary depending on which driver is in use.
Returns: JE_FALSE if unsuccessful due to an error. JE_TRUE otherwise. Note that a driver without an implementation may return true despite no actual action.

Notes:
ENGINE.C: this hits the driver activation code to manage surfaces and exclusive modes for devices (WM_ACTIVATEAPP)

JETAPI jeBoolean jeEngine_AddBitmap(jeEngine* Engine, jeBitmap* Bitmap, jeEngine_BitmapType Type);

This function adds jeBitmap Bitmap to jeEngine Engine with jeEngine_BitmapType Type so that it may be used in subsequent calls to Engine. Note that if Bitmap is to be used in other modules it must be added to them as well. It appears that this is implemented via reference counting, therefore it is safe to add a bitmap to an engine more than once, and little or no additional memory should be used. Note that this function may not be called between jeEngine_BeginFrame and jeEngine_EndFrame.
Returns: JE_TRUE on success, JE_FALSE otherwise.

jeBoolean jeEngineAttachAll(jeEngine* Engine);

This function associates jeEngine Engine's bitmap list with it's associated driver. This function is called (indirectly) by jeEngine_BeginFrame. I don't believe this needs to be in the public API.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_BeginFrame(jeEngine* Engine, jeCamera* Camera, jeBoolean ClearScreen);

incomplete

This function puts jeEngine Engine into "drawing" mode. Between this call and a matching jeEngine_EndFrame call, all drawing/rendering must be done. Camera is the jeCamera through which the rendering will be done. ClearScreen tells the engine whether or not to wipe the back-buffer before drawing begins.
Returns: JE_TRUE on success, JE_FALSE otherwise.

Questions:
Is it possible to have more than one Camera object and switch between them utilizing the Camera specifier above? Would doing this cause any delay? In other words is there any information that has to be generated once a camera is set, but not generally regenerated unless the camera is changed?

jeBoolean jeEngine_BitmapListInit(jeEngine* Engine);

This function initializes jeEngine Engine's bitmap list. This function is called by jeEngine_Create. I don't believe this needs to be in the public API.
Returns: JE_TRUE on success, JE_FALSE otherwise.

jeBoolean jeEngine_BitmapListShutdown(jeEngine* Engine);

This function destroys jeEngine Engine's bitmap list, freeing up all associated resources. This function is called by jeEngine_Free (and jeEngine_Destroy, by extension). I don't believe this needs to be in the public API.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeEngine* jeEngine_Create(HWND hWnd, const char* AppName, const char* DriverDirectory);

This function constructs a jeEngine object and returns it. hWnd is a handle to a window object from which Jet3D will get its focus and to which, in a windowed mode, it will render. AppName is the name of the application. Exactly how this is used, I don't know. The DriverDirectory is the directory in which jeEngine will look for its drivers upon creation.
Returns: the jeEngine object on success, otherwise NULL.

JETAPI jeBoolean jeEngine_CreateRef(jeEngine* Engine);

This function increase the reference count of jeEngine Engine by one.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI void* jeEngine_D3DDriver(void);

This function returns a pointer to the function hook to the Direct3D driver.
Returns: a pointer to the driver.

jeBoolean jeEngine_DebugPrintf(jeEngine* Engine, const char* String, ....);

This function outputs to a fixed position on the screen, use this much like printf.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI void jeEngine_Destroy(jeEngine** pEngine);

This function decreases the reference count of jeEngine pEngine by one. If the reference count goes to 0 the all associated resources are freed. jeEngine_Destroy replaces jeEngine_Free. It expands jeEngine_Free by accepting a pointer to a pointer to a jeEngine object. On return pEngine will point to a NULL value. Note that jeEngine_Destroy is buggy currently. _Destroy NULLs the pointer whether or not the resources are freed.
Returns: nothing.

jeBoolean jeEngine_DetachAll(jeEngine* Engine);

This function disassociates jeEngine Engine's bitmap list from it's driver. This function is called indirectly by jeEngine_Free (and jeEngine_Destroy, by extension). I don't believe this needs to be in the public API.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeEngine_DrawBitmap(const jeEngine* Engine, const jeBitmap* Bitmap, const jeRect* Source, uint32 x, uint32 y);

This function draws jeBitmap Bitmap into jeEngine Engine's current active back-buffer. If there is more than one back-buffer, the bitmap will not be rendered until the next call to jeEngine_EndFrame. Source specifies the part of the jeBitmap to draw. x and y specify the point in screen-space where drawing will begin. Bitmap must already have been added to Engine via a call to jeEngine_AddBitmap. Bitmap should be of jeEngine_BitmapType JE_ENGINE_BITMAP_TYPE_2D. See jeEngine_DrawBitmap3D for JE_ENGINE_BITMAP_TYPE_3D jeBitmaps.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeEngine_DrawBitmap3D(const jeEngine* Engine, const jeBitmap* Bitmap, const jeRect* pRect, uint32 x, uint32 y);

This function draws jeBitmap Bitmap into jeEngine Engine's current active back-buffer. If there is more than one back-buffer, the bitmap will not be rendered until the next call to jeEngine_EndFrame. pRect specifies the part of the jeBitmap to draw. x and y specify the point in screen-space where drawing will begin. Bitmap must already have been added to Engine via a call to jeEngine_AddBitmap. Bitmap should be of jeEngine_BitmapType JE_ENGINE_BITMAP_TYPE_3D. See jeEngine_DrawBitmap for JE_ENGINE_BITMAP_TYPE_2D jeBitmaps. Looking at the source these two functions are clearly implemented differently. _DrawBitmap uses the decalling routines of the driver, whereas _DrawBitmap3D renders the bitmap using screen-space polygons. What this means to users, I don't know.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI void jeEngine_EnableFrameRateCounter(jeEngine* Engine, jeBoolean Enabled);

This function sets or resets a framerate/debug information display at the upper left of the screen based on Enabled.
Returns: nothing.

JETAPI jeBoolean jeEngine_EndFrame(jeEngine* Engine);

This function ends the current drawing/rendering session and renders the current active back-buffer to the screen. The buffer is then added to the end of the back-buffer chain. Note that all drawing/rendering must be complete before this function is called.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI void jeEngine_FillRect(jeEngine* Engine, const jeRect* Rect, const JE_RGBA* Color);

This function renders a rectangle of solid color to the current active back-buffer. As with all rendering functions, this must be called between an appropriate jeEngine_BeginFrame and jeEngine_EndFrame pair.
Returns: nothing.

JETAPI jeBoolean jeEngine_FlushScene(jeEngine* Engine);

This function forces a rendering of all world/poly data. I'm not completely sure of this one.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI void jeEngine_Free(jeEngine* Engine);

DEPRECATED -- See jeEngine_Destroy

This function decreases the reference count for jeEngine Engine. If the reference count goes to 0, jeEngine Engine is deleted freeing up all associated resources.
Returns: nothing.

Notes:
ENGINE.C: Don't use this :

JETAPI jeBoolean jeEngine_GetDefaultRenderFlags(jeEngine* pEngine, uint32* RenderFlags);

This function returns the rendering flags currently set for jeEngine pEngine in RenderFlags.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_GetDeviceCaps(jeEngine* pEngine, jeDeviceCaps* DeviceCaps);

This function returns a jeDeviceCaps object DeviceCaps which contains information about the current driver for jeEngine pEngine.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_GetDriverAndMode(const jeEngine* Engine, jeDriver** Driver, jeDriver_Mode** DriverMode);

This function returns the current driver and mode of jeEngine Engine in Driver and DriverMode, respectively.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeDriver_System* jeEngine_GetDriverSystem(jeEngine* Engine);

Returns the jeDriver_System object currently associated with the jeEngine Engine.
Returns: the jeDriver_System object, or NULL on failure.

JETAPI jeBoolean jeEngine_GetFrameState(const jeEngine* Engine, jeEngine_FrameState* FrameState);

This function returns the current state of the jeEngine Engine. If jeEngine_GetFrameState is called between corresponding _BeginFrame and _EndFrame calls, then the jeEngine_FrameState of FrameState_Begin is returned in FrameState indicating that jeEngine is receptive to drawing/rendering type calls. Otherwise FrameState_None is returned in FrameState.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_GetGamma(jeEngine* Engine, float* pGamma);

This function returns the current gamma setting for jeEngine Engine.
Returns: JE_TRUE on success, JE_FALSE otherwise.

jeBoolean jeEngine_InitFonts(jeEngine* Engine);

This function initializes fonts within jeEngine Engine. This function is called by jeEngine_Create. I don't believe this needs to be in the public API.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_IsValid(const jeEngine* Engine);

This function performs some basic checks to validate that the jeEngine Engine is a valid jeEngine object
Returns: JE_TRUE if Engine is valid, JE_FALSE otherwise.

HINSTANCE jeEngine_LoadLibrary(const char* lpLibFileName, const char* DriverDirectory);

This function loads the driver library named by lpLibFileName from directory DriverDirectory and returns a handle to it. This function is called indirectly by _SetDriverAndMode. I don't believe this needs to be in the public API.
Returns: A handle to the loaded library or NULL on failure.

JETAPI jeBoolean jeEngine_Printf(jeEngine* Engine, int32 x, int32 y, const char* String, ...);

This function outputs a formatted string to the specified screen-space coordinates of the current active back-buffer. This function should be called between the appropriate matching pair of jeEngine_BeginFrame and jeEngine_EndFrame calls. The current font is used for rendering. Use this much like you would use stdio's printf.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_RegisterDriver(jeEngine* Engine, void* HookProc);

This function attaches the driver associated with the driver hook function HookProc to jeEngine Engine. I'm assuming this is all handled by _SetDriverAndMode, and generally this function would not need to be used.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeEngine_RegisterObject(HINSTANCE DllHandle);

This function registers an object dll that has been previously loaded and has the handle DLLHandle with the jeEngine.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean JETCC jeEngine_RegisterObjects(char* DLLPath);

This function loads and registers all object libraries in the directory DLLPath with the jeEngine.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_RemoveBitmap(jeEngine* Engine, jeBitmap* Bitmap);

This function removes jeBitmap Bitmap from jeEngine Engine. This is implemented via reference counts, so each AddBitmap must be matched by a RemoveBitmap.
Returns: JE_TRUE on success, JE_FALSE otherwise..

JETAPI void JETCC jeEngine_RenderPoly(const jeEngine* Engine, const JE_TLVertex* Points, int NumPoints, const jeBitmap* Texture, uint32 Flags);

This function renders an optionally textured polygon to the current active back-buffer. JE_TLVertex is a Transformed Lit Vertex in screen-space. If Texture is NULL, the polygon will be rendered Gouraud shaded, otherwise the world specified must contain the specified texture. The Flags field should be composed of a combination of the JE_RENDER_FLAG_ constants found in jeTypes.h. The points in the JE_TLVertex array must be defined in the proper winding order, clockwise as viewed from the front of the polygon.
Returns: nothing.

Notes:
from GENESIS.H: // Texture should have been a TYPE_3D
Questions:
Can there be any number of co-planar vertices? Must they define a convex polygon?

JETAPI void JETCC jeEngine_RenderPolyArray(const jeEngine* Engine, const JE_TLVertex** pPoints, int* pNumPoints, int NumPolys, const jeBitmap* Texture, uint32 Flags);

This function renders multiple optionally textured polygons to the screen. pPoints is the array of polygons, pNumPoints is an array for the number of points in each polygon, and NumPolys is the number of polygons. See _RenderPoly for more information.
Returns: nothing.

jeBoolean jeEngine_ResetDriver(jeEngine* Engine);

This function resets the driver currently associated with jeEngine Engine.
Returns: JE_TRUE on success, JE_FALSE otherwise.
Notes:
ENGINE.H: Resets the current driver

JETAPI jeBoolean jeEngine_ScreenShot(jeEngine* Engine, const char* FileName);

This function save the current contents of the front-buffer to a .bmp file. This is implemented via the driver and so there may be some implementation variations depending on which driver is in use.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_SetDefaultRenderFlags(jeEngine* pEngine, uint32 RenderFlags);

This function set the rendering options for jeEngine pEngine to RenderFlags.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_SetDriverAndMode(jeEngine* Engine, HWND hWnd, jeDriver* Driver, jeDriver_Mode* DriverMode);

This function sets the jeDriver and jeDriver_Mode for jeEngine Engine to Driver and DriverMode, respectively. hWnd is a pointer to the appriopriate MS windows handle.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_SetGamma(jeEngine* Engine, float Gamma);

This function sets the gamma correction value that the jeEngine object will use for all further drawing or rendering.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI jeBoolean jeEngine_ShutdownDriver(jeEngine* Engine);

This function shuts down the current driver and restores the display to its original state before ANY calls to jeEngine_SetDriverAndMode.
Returns: JE_TRUE on success, JE_FALSE otherwise.

jeBoolean jeEngine_ShutdownFonts(jeEngine* Engine);

This function frees all resources from jeEngine Engine associated with fonts. This is called by jeEngine_Free (and jeEngine_Destroy, by extension). I don't see why this needs to be in the public API.
Returns: JE_TRUE on success, JE_FALSE otherwise.

JETAPI void* jeEngine_SoftwareDriver(void);

This function returns a pointer to the function hook to the software driver.
Returns: a pointer to the driver.

void jeEngine_UpdateGamma(jeEngine* Engine);

This function updates the display driver for jeEngine Engine with it's gamma settings. This is called by jeEngine_SetGamma. I don't see why this needs to be in the public API.
Returns: nothing

JETAPI jeBoolean jeEngine_UpdateWindow(jeEngine* Engine);

This function tells the current driver to update it's window rect. This is usually called as a result of a window move, resize, etc. This is implemented by each driver individually and the implementation may vary.
Returns: JE_TRUE on success, JE_FALSE otherwise.