The geEngine object is the container for the geDriver_System object, the geWorld object, and the geBitmap object. The primary job of the geEngine object is to provide a fast, and efficient interface to the output device, via the geDriver_System object.
The geEngine object is the container for all 2d objects. The geEngine object is responsible for providing an interface to the 2d primary display device. This includes drawing geBitmaps, text, etc. All info pertaining to 3d is stored in other objects such as geActors, geWorlds, etc. Each 3d object is optimized to render its own set of primitives. It is the engines job to provide an interface to the primary display device for those objects. If you are familiar with DirectX, you can think of the geEngine object as a DirectDraw object.
When the geEngine object is created, it creates a geDriver_System object internally. It is the responsibility of the user to obtain the system, and to set a valid Driver/Mode (geEngine_SetDriverAndMode) combination in the geEngine object.
The geEngine object uses the standard technique of double-buffering (whenever possible) to achieve non-flickering animation. This flickering is the result of being able to incrementally see what's being drawn into the front-buffer as it is being drawn.
To counter this problem, the engine will create and maintain an n number of buffers whenever a valid Driver/Mode is set. These buffers are what the engine will use to draw into, for ANY of its drawing/rendering API's. A buffer can be one of two roles (or both in the case of only one buffer). It can either be the front-buffer, or a back-buffer. The front-buffer is the buffer that is currently visible. The back-buffers are the temporary buffers used to draw in while waiting to have the role of the front-buffer. At least one of the buffers must be the front-buffer at any given time. In the case of the engine only creating one buffer, that buffer will ALWAYS be the front-buffer, and all drawing will happen in this buffer (hence, all drawing will be visible immediately, and flickering will occur). In the case that the engine creates more than one buffer, one of them will be the front-buffer, while the others will remain back-buffers. In this case, all drawing will happen in the current active back-buffer, and any drawing won't be visible until the current active back-buffer that is being used changes it's role to the front-buffer. Note that only one front-buffer may exist at any given time, so in the case of a role change from back-buffer to front-buffer, the old front-buffer changes its role to a back-buffer. The engine then chooses the next available back-buffer in the chain as the active buffer to draw in.
All drawing API's should be called AFTER geEngine_BeginFrame, and BEFORE geEngine_EndFrame. This is because, geEngine_BeginFrame will set up the current active back-buffer, and prepare it to be drawn in to for that frame. This includes clearing specified regions of the current back-buffer, etc. To see the contents of the back-buffer, geEngine_EndFrame must be called. geEngine_EndFrame will make the current back-buffer visible (changes it's role to the front-buffer), and set the old front-buffer to the next available back-buffer in the chain.
Before you can use a geBitmap in any module, you must add the geBitmap to that module first. For example, if you were planning on using geEngine_DrawBitmap, you must first add the geBitmap to the geEngine module (see geEngine_AddBitmap). Please note that adding a geBitmap to a geEngine module, does not allow you to use the geBitmap in other modules. You must add the geBitmap to each and every module that you plan on using the geBitmap with. Also note that you cannot add a geBitmap to a geEngine, while in the middle of a drawing frame (in between calls to geEngine_BeginFrame, and geEngine_EndFrame)
Like geBitmap's, you cannot use a geWorld object with the geEngine, unless you have added the geWorld to the geEngine first (see geEngine_AddWorld). Also, like geBitmap's, you cannot add a geWorld to a geEngine, while in the middle of a drawing frame (in between calls to geEngine_BeginFrame, and geEngine_EndFrame).
geBoolean geEngine_AddBitmap(geEngine *Engine, geBitmap *Bitmap)
Description: Adds a geBitmap to a geEngine object, and increases the reference count of the geBitmap object by one. A geBitmap can be added to a geEngine more than once.
Parameters:
| Engine | A geEngine object that will contain the geBitmap. |
| Bitmap | The geBitmap object that will be added to the geEngine object. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise
geBoolean geEngine_AddWorld(geEngine *Engine, geWorld *World)
Description: 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 more than once.
Parameters:
| Engine | The geEngine object that will contain the new world. |
| World | A geWorld object that will be added to the geEngine object. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_BeginFrame(geEngine *Engine, geCamera *Camera, geBoolean ClearScreen)
Description: Prepares the geEngine object for a new frame, and sets up the current active back-buffer for drawing. Any Drawing, or Rendering API's MUST be called after geEngine_BeginFrame.
Parameters:
| Engine | The geEngine object that will be prepared for a new frame. |
| Camera | A geCamera object that contains a valid geRect set, that will be used to define the active region of the back-buffer. (Not fully implemented) |
| ClearScreen | A geBoolean that if set to GE_TRUE, will wipe the back-buffer. Otherwise, the back-buffer will be preserved from the previous frame. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geEngine *geEngine_Create(HWND hWnd, const char *AppName, const char *DriverDirectory)
Description: Creates a geEngine object.
Parameters:
| hWnd | Handle to the window that should belong to Genesis. This window handle will be what Genesis receives it's focus from. In a window video mode (see geEngine_SetDriverAndMode), it will also be what is rendered into. |
| AppName | *REMOVE* |
| DriverDirectory | The directory where the geEngine object will look for drivers upon creation. |
Returns: Returns a valid geEngine object if the function succeeds, NULL otherwise.
geBoolean geEngine_DrawBitmap(geEngine *Engine, geBitmap *Bitmap, geRect *Source, int32 x, int32 y)
Description: 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.
Parameters:
| Engine | The geEngine that will be used to draw the bitmap. |
| Bitmap | The geBitmap object to draw. |
| Source | Pointer to a geRect structure that defines what portion of the bitmap will be drawn. |
| x | Specifies the row (in pixel space) where the bitmap will start drawing. |
| y | Specifies the column (in pixel space) where the bitmap will start drawing. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_EnableFrameRateCounter(geEngine *Engine, geBoolean Enable)
Description: Enables detailed debug info, using the current active font.
Parameters:
| Engine | The geEngine that should display debug info. |
| Enable | A geBoolean that should be GE_TRUE for debug info. GE_FALSE otherwise. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_EndFrame(geEngine *Engine)
Description: 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.
Parameters:
| Engine | The geEngine object that previously called geEngine_BeginFrame. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
void geEngine_FillRect(geEngine *Engine, const GE_Rect *Rect, const GE_RGBA *Color)
Description: Fills a specified region of the current active back-buffer with a specified color.
Parameters:
| Engine | The geEngine that was used to create the back-buffer in question. |
| Rect | Address of a geRect structure that contains the region of the buffer to fill. |
| Color | Address of a GE_RGBA structure that contains the color that the fill will use. |
Returns: Nothing.
void geEngine_Free(geEngine *Engine)
Description: Destroys a geEngine object.
Parameters:
| Engine | The geEngine object to be destroyed. |
Returns: Nothing.
geBoolean geEngine_GetGamma(geEngine *Engine, float *Gamma)
Description: Gets the current gamma correction value that the geEngine object is currently using for all drawing, and rendering API's.
Parameters:
| Engine | The geEngine that the gamma value is to be obtained from. |
| Gamma | Address of a float that will be filled with the current gamma value. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_Printf(geEngine *Engine, int32 x, int32 y, const char *Str, ...)
Description: Prints a formatted NULL terminated string using the currently selected font.
Parameters:
| Engine | The geEngine that will be used to print the text. |
| x | Specifies the row (in pixel space) of the starting point of the text. |
| y | Specifies the column (in pixel space) of the starting point of the text. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_RemoveBitmap(geEngine *Engine, geBitmap *Bitmap)
Description: Removes a previously added geBitmap object from a geEngine object, and decreases the reference count of the geBitmap object by one.
Parameters:
| Engine | A geEngine object that contains the geBitmap. |
| Bitmap | The geBitmap object that will be removed from the geEngine object. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_RemoveWorld(geEngine *Engine, geWorld *World)
Description: Removes a previously added geWorld object from a geEngine object, and decreases the reference count of the geWorld object by one.
Parameters:
| Engine | A geEngine object that contains the geWorld. |
| World | The geWorld object that will be removed from the geEngine object. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
void geEngine_RenderPoly(geEngine *Engine, geWorld *World, const GE_TLVertex *Points, int NumPoints, const geBitmap *Texture, uint32 Flags)
Description: 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.
Parameters:
| Engine | The geEngine that will be used to render the poly. |
| World | The geWorld that is the container for the Texture being used for this operation. |
| Points | Pointer to an array of vertices that define the winding of the poly. |
| NumPoints | Number of points in the poly. |
| Texture | Texture to be mapped onto the poly. If this is NULL, then the poly is gouraud shaded. |
| Flags | One or more of the following flags defining how the poly is rendered: |
| None |
Returns: Nothing.
geBoolean geEngine_RenderWorld(geEngine *Engine, geWorld *World, geCamera *Camera, float Time)
Description: 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.
Parameters:
| Engine | The geEngine object that will be used to render the geWorld. |
| World | The geWorld object that will be rendered. |
| Camera | A geCamera object that will define the 3d viewing area, as well as the POV (Point Of View), and orientation info. |
| Time | This is currently not implemented, and should be set to 0. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_ScreenShot(geEngine *Engine, const char *FileName)
Description: Grabs the current contents of the front-buffer, and saves it to a file, in .BMP format.
Parameters:
| Engine | The geEngine that contains the front-buffer in question. |
| FileName | Address of a NULL terminated string that contains the full path of the output file. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_SetDriverAndMode(geEngine *Engine, geDriver *Driver, geDriver_Mode *DriverMode)
Description: 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.
Parameters:
| Engine | The geEngine object that the Driver/Mode change will be applied to. |
| Driver | A geDriver object that was previously enumerated with geDriver_SystemGetNextDriver. |
| DriverMode | A geDriver_Mode object that was previously enumerated with geDriver_etNextMode. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_SetGamma(geEngine *Engine, float Gamma)
Description: Sets the current gamma correction value that the geEngine object is to use for all further drawing, or rendering API's.
Parameters:
| Engine | The geEngine that is to get the new gamma value. |
| Gamma | The new gamma value. The valid range is from 0 to 3. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.
geBoolean geEngine_ShutdownDriver(geEngine *Engine, geDriver *Driver, geDriver_Mode *DriverMode)
Description: Shuts down any current Driver/Mode combo, and restores the display to the original prior to the very first call to geEngine_SetDriverAndMode.
Parameters:
| Engine | The geEngine object that the will shutdown it's current driver/mode. |
Returns: Returns GE_TRUE is the function succeeds, GE_FALSE otherwise.