geEngine
Description: Maintains the driver interface, as well as the bitmaps attached to the driver.
Source file: …\genesis3d\OpenSource\Engine\engine.h
Functions: Activate, AddBitmap, AddWorld, BeginFrame, Create, DrawBitmap, EnableFrameRateCounter, EndFrame, FillRect, Free, GetDriverSystem, GetGamma, Printf, RemoveBitmap, RemoveWorld, RenderPoly, RenderPolyArray, RenderWorld, ScreenShot, SetDriverAndMode, SetGamma, ShutdownDriver, UpdateWindow
The following are defined in System:
Types: geEngine_FrameState, geEngine_WorldList, geEngine
And also here, in geDriver:
Types: geEngine_FrameState, geEngine_WorldList, geEngine
Additions for Genesis3D v1.6: DrawAlphaBitmap, SetFogEnable
Functions:
GENESISAPI geBoolean geEngine_Activate(geEngine* Engine, geBoolean bActive);
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. D3D seems to implement this, Glide does not seems to implement this (currently the Glide implementation just returns TRUE), SoftDrv seems to implement it, and SoftDrv2 seems to implement it.
Returns: GE_FALSE if unsuccessful due to an error. GE_TRUE otherwise. Note that a driver without an implementation may return true despite not actual action.
Notes:
from opensource/source/engine/engine.c -- this hits the driver activation code to manage surfaces and exclusive modes for devices (WM_ACTIVATEAPP)
GENESISAPI geBoolean geEngine_AddBitmap(geEngine* Engine, geBitmap* Bitmap);
This function adds a geBitmap to a geEngine so that it may be used in calls to the geEngine. Note that if the geBitmap 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 geEngine_BeginFrame and geEngine_EndFrame.
Notes:
from Genesis3D Api Reference: Adds a geBitmap to a geEngine object, and increases the reference count of the geBitmap object by 1. A geBitmap can be added to a geEngine more than once.
GENESISAPI geBoolean geEngine_AddWorld(geEngine* Engine, geWorld* World);
This function adds a geWorld to a geEngine. This is implemented via reference counting and therefore the world may be added mutiple times. Note that this function may not be called between geEngine_BeginFrame and geEngine_EndFrame.
Notes:
from Genesis3D Api Reference: Adds a geWorld object to a geEngine object, and increases the reference count of the world by one. A geWorld object can be added to a geEngine object more than once.Note from Jeff: The geEngine_AddWorld() function will increase the reference count of the geWorld and copy a reference to the engine's world array. This array is used to keep track of all the worlds in the engine.
Questions:
What does it mean for an engine to have the same world added multiple times? Furthermore what does it mean for an engine to have multiple worlds added to it?
GENESISAPI geBoolean geEngine_BeginFrame(geEngine* Engine, geCamera* Camera, geBoolean ClearScreen);
This function puts the geEngine into "drawing" mode. Between this call and a matching geEngine_EndFrame call all drawing/rendering must be done. Camera is the camera through which the rendering will be done. ClearScreen tells the engine whether or not to wipe the back-buffer before drawing begins.
Notes:
from Genesis3D Api Reference: Prepares the geEngine object for a new frame, and sets up the current active back-buffer for drawing. Any Drawing, or Rendering APIs MUST be called after geEngine_BeginFrame.
Questions:
Is it possible to have more than one Camera object and switch between them utilizing the Camera specifier above? "Yes, hundreds." Would doing this cause any delay? "Switching from one to the other doesn't, rendering more than one at a time does." 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? "Yes, The camera(s) should all change/update (imo) data as the game progresses, but not necessarily need to be rendered until needed. "Answers provided by Securitron in green above.
GENESISAPI geEngine* geEngine_Create(HWND hWnd, const char * AppName, const char * DriverDirectory);
This function is the constructor for a geEngine object. hWnd is a handle to a window object from which Genesis will get its focus and to which, in a windowed mode, Genesis will render. The is a "*Remove*" reference in the online docs for the AppName arg, perhaps this is to be deprecated and may not provide much if any facility currently. The DriverDirectory is the directory in which geEngine will look for its drivers upon creation.
Notes:
from Genesis3D Api Reference: Creates a geEngine object. hWnd is a handle to the window that should belong to Genesis. This window handle will be what Genesis received its focus from. In a windowed video mode it will also be what is rendered into. DriverDirectory is the directory where Genesis will look for drivers upon creation.
GENESISAPI geBoolean GENESISCC geEngine_DrawBitmap(const geEngine* Engine, const geBitmap* Bitmap, const geRect* Source, uint32 x, uint32 y);
This function draws the specified geBitmap into the geEngine's current active back-buffer. If there is more than one back-buffer, the bitmap will not be rendered until the next call to geEngoine_EndFrame. Source specifies the part of the geBitmap to draw. x and y specify the point in pixel-space where drawing will begin.
Notes:
from GENESIS.H: //DrawBitmap & RenderPoly : must Engine_AddBitmap first!
from Genesis3D Api Reference: Draws a geBitmap into the current active back-buffer. If there is more than one back-buffer, the bitmap will not be seen until the next call to geEngine_EndFrame.
Questions:
Does x,y specify the top-left corner? Or is it some other corner?
GENESISAPI geBoolean GENESISCC geEngine_DrawAlphaBitmap(geEngine* Engine, geBitmap* Bitmap, geVec3d* VertUVArray, geCamera* ClipCamera, GE_Rect* PixelRect, GE_Rect* PercentRect, geFloat Alpha, GE_RGBA* RGBA_Array);
Draws a bitmap with alpha transparancy
Notes:
ClipCamera: if null, uses full screen.
PixelRect: pixels in the "camera" view
PercentRect: percent of the "camera" view
GENESISAPI void geEngine_EnableFrameRateCounter(geEngine* Engine, geBoolean Enabled);
This function sets or resets a framerate/debug information display at the upper left of the screen based on Enabled.
Returns: nothing.
Notes:
from Genesis3D Api Reference: Enable detail debug info, using the current active font.
GENESISAPI geBoolean geEngine_EndFrame(geEngine* 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.
Notes:
from Genesis3D Api Reference: Ends the current drawing session in the geEngine, makes the current active back-buffer visible, and flips this buffer to the next buffer in the chain.
GENESISAPI void geEngine_FillRect(geEngine* Engine, const GE_Rect* Rect, const GE_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 geEngine_BeginFrame and geEngine_EndFrame pair. Note the inclusion of ALPHA.
Returns: nothing.
Notes:
from Genesis3D Api Reference: Fills a specified region of the current active back-buffer with a specified color.
GENESISAPI void geEngine_Free(geEngine* Engine);
This function destroys the specified geEngine object.
Returns: nothing.
Notes:
from Genesis3D Api Reference: Destroys a geEngine object.
Question:
Are geEngines stored via a reference counting scheme? Is it therefore possible for this function call to decrease a reference count but not actually free any resources?
GENESISAPI geDriver_System* geEngine_GetDriverSystem(geEngine* Engine);
Returns the geDriver_System object currently associated with the specified geEngine object.
Returns: the geDriver_System object, or NULL on failure.
GENESISAPI geBoolean geEngine_GetGamma(geEngine* Engine, geFloat* Gamma);
This function returns the current gamma settings for the geEngine.
Notes:
from Genesis3D Api Reference: Gets the current gamma correction value that the geEngine object is currently using for all drawing, and rendering API's.
GENESISAPI geBoolean geEngine_Printf(geEngine* Engine, int32 x, int32 y, const char * String, ...);
This function outputs a formatted string to the specified pixel-space coordinates of the current active back-buffer. This function should be called between the appropriate matching pair of geEngine_BeginFrame and geEngine_EndFrame calls. The current font is used for rendering.
Notes:
from Genesis3D Api Reference: Prints a formatted NULL terminated string using the currently selected font.
Questions:
Does the engine handle clipping?
GENESISAPI geBoolean geEngine_RemoveBitmap(geEngine* Engine, geBitmap* Bitmap);
This function removes the specified geBitmap from the specifed geEngine object. This is implemented via reference counts, so each AddBitmap must be matched by a RemoveBitmap.
Notes:
from Genesis3D Api Reference: Removes a previously added geBitmap object from a geEngine object, and decreases the reference count of the geBitmap object by one.
GENESISAPI geBoolean geEngine_RemoveWorld(geEngine* Engine, geWorld* World);
This functions removes the specified geWorld object from the specified geEngine object. This is implement via reference counting, so each AddWorld must be matched by a RemoveWorld.
Notes:
from Genesis3D Api Reference: Removes a previously added geWorld object from a geEngine object, and decreases the reference count of the geWorld object by one.Note from Jeff: The geEngine_RemoveWorld() function will check to see if there are multiple references to the geWorld, if so then it decreases the reference count and returns GE_TRUE. If there is only one reference then it removes the geWorld from the engine's world array and calls the geWorld_Free() function.
GENESISAPI void GENESISCC geEngine_RenderPoly(const geEngine* Engine, const GE_TLVertex* Points, int NumPoints, const geBitmap* Texture, uint32 Flags);
This function renders an optionally textured polygon to the current active back-buffer. GE_TLVertex is a Transformed Lit Vertex and appears to be a reference to screen-space. If Texture is null, the polygon will be rendering Gouraud shaded. The world specified must contain the specified texture. The Flags field seems to be unused currently. The points in the GE_TLVertex array must be defined in the proper winding order.
Notes:
from GENESIS.H: //RenderPoly : if Texture is null, we Gouraud shade.
from Genesis3D Api Reference: Renders a poly to the current active back-buffer using the geEngine object supplied. If there is more than one back-buffer, the poly will not be seen until the next call to geEngine_EndFrame is called, and the buffer is made visible. This function must be called AFTER geEngine_BeginFrame, and BEFORE geEngine_EndFrame.
Questions:
Can there be any number of co-planar vertices? Must they define a convex polygon? What is meant be winding order? Will this define a front and back to the polygon? Is screen-space 2D or 3D? If it is 3D is it perspective-rendered? How does screen-space differ from pixel-space and camera-space? Is any sort of clipping or Z-buffering done?
GENESISAPI void GENESISCC geEngine_RenderPolyArray(const geEngine* Engine, const GE_TLVertex* * pPoints, int * pNumPoints, int NumPolys, const geBitmap* Texture, uint32 Flags);
This function renders multiple optionally textured polygons to the screen. I assume this is implemented much like geEngine_RenderPoly, so see the details above.
Questions:
Much like geEngine_RenderPoly above, Z-buffered? Clipped? 3D or 2D?
GENESISAPI geBoolean geEngine_RenderWorld(geEngine* Engine, geWorld* World, geCamera* Camera, geFloat Time);
This function handles the actual rendering of the World to the current active back-buffer. This must be done between the appropriate matching geEngine_BeginFrame and geEngine_EndFrame calls. The Time arg is currently un-implemented.
Notes:
from Genesis3D Api Reference: Renders the entire contents of a geWorld into the current active back-buffer. NOTE - If there is more than one back-buffer, then this buffer will not be visible until the next call to geEngine_Endframe. This function MUST be called after geEngine_BeginFrame, and before geEngine_EndFrame.
Questions:
How does this sync with other rendering calls such as geEngine_RenderPoly? Is the Z-Buffering handled appropriately or should renders for objects in front of the world be handled after calling RenderWorld?
GENESISAPI geBoolean geEngine_ScreenShot(geEngine* 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. D3D does not implement this currently and returns GE_FALSE, Glide appears to implement this, SoftDrv does not implement this and currently returns GE_FALSE, SoftDrv2 does not implement this and currently returns GE_FALSE;
Notes:
from Genesis3D Api Reference: Grabs the current contents of the front-buffer, and saves it to a file, in .BMP format.
I believe someone has implemented this for D3D, check the Genesis3D bulletin board.
GENESISAPI geBoolean geEngine_SetDriverAndMode(geEngine* Engine, geDriver* Driver, geDriver_Mode* DriverMode);
This function sets the Driver and Mode for the engine.
Notes:
from Genesis3D Api Reference: Set the current driver and mode that the geEngine object will use for all further drawing, and rendering operations. Note that this function can be called anytime outside geEngine_BeginFrame/geEngine_EndFrame.
Questions:
Presumably this must be called outside of geEngine_BeginFrame and geEngine_EndFrame. Must this be called before any other function calls? Can this be changed at any time?
GENESISAPI geBoolean geEngine_SetGamma(geEngine* Engine, geFloat Gamma);
This function sets the gamma correction value that the geEngine object will use for all further drawing or rendering. The range for gamma is 0 to 3.
Notes:
from Genesis3D Api Reference: Sets the current gamma correction value that the geEngine object is to use for all further drawing, or rendering API's.
Questions:
Does it matter where this is called? I'm sure that it can be called outside of Begin/End Frame, how about inside? Can it be called for individual rendering? Could this be used to effect gamma correction on a per render basis?
GENESISAPI geBoolean geEngine_SetFogEnable(geEngine* Engine, geBoolean Enable, geFloat r, geFloat g, geFloat b, geFloat Start, geFloat End);
Added for Genesis3D v1.6
Notes from kdtop: This fills the world with fog. It does not affect frame rate like geFog's do. (see geWorld_AddFog)
GENESISAPI geBoolean geEngine_ShutdownDriver(geEngine* Engine);
This function shuts down the current driver and restores the display to its original state before ANY calls to geEngine_SetDriverAndMode.
Notes:
from Genesis3D Api Reference: Shuts down any current Driver/Mode combo, and restores the display to the original prior to the very first call to geEngine_SetDriverAndMode.
GENESISAPI geBoolean geEngine_UpdateWindow(geEngine* 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. Currently D3D implements this, Glide does not implement this returning GE_TRUE immediately, SoftDrv similarly returns GE_TRUE immediately, SoftDrv2 does not seem to provide any implementation. It may be that for Glide and SoftDrv nothing needs to be done for this function so that nothing IS a full implementation.
Notes:
from Opensource/source/engine/engine.c: this call updates the drivers with a new rect to blit to (usually the result of a window move or resize)
There appear to be 4 drivers: D3D, Glide, SoftDrv, and SoftDrv2. I THINK the difference in the 2 software drivers is one (SoftDrv, I think) implement 3DNow support while the other does not.