4. Surface Clearing

HERMES provides support for clearing surfaces (i.e. blocks of memory filled with pixels) quickly and cleanly. Clearing routines exist in C, x86 assembler and MMX assembler versions and thus are fast. However, keep in mind that if you have the chance of using a hardware accelerated routine for this, it will still be faster.

4.1 HermesHandle Hermes_ClearerInstance()

Not much to say about this, same as the other *Instance() functions. You have to call this to obtain a handle before you use any other clearing routines.

This routine can return zero upon failure.

4.2 void Hermes_ClearerReturn(HermesHandle handle)

Again, if you are finished clearing surfaces (and that means completely finished, call it only at the end of a program, not every time you have just cleared a surface) use this function to free up any memory inside Hermes.

4.3 int Hermes_ClearerRequest(HermesHandle handle,HermesFormat *format)

This function will tell HERMES to prepare a special clearer for a subsequent clear operation. Again, you may call this as often as you want, once it has been set up, subsequent calls will be cached.

Zero will be returned if your handle is invalid or the format you requested cannot be cleared (all formats are implemented, thus you will have to request a pretty fucked up format in order to fail this :). Upon success, any non-zero value may be returned.

4.4 int Hermes_ClearerClear(...)

ClearerClear is the function that actually does the work. The request function has to be called before this, otherwise it will fail. The following variables have to be passed to the function:

• HermesHandle handle - the handle you have obtained by calling Hermes_ClearerInstance().
• void *pixels - the buffer to clear. It is void because it might be any format that has been requested in Hermes_ClearerRequest()
• int x1 - Upper left corner x coordinate IN PIXELS not bytes
• int y1 - Upper left corner y coordinate in pixels
• int width - Width of area to be cleared in pixels
• int height - Height of area to be cleared in pixels
• int pitch - Amount IN BYTES to add in order to get from the beginning of a scanline to the beginning of the next. See the conversion section for more on this.
• int32 r - For direct colour, the red component, between 0-255 !!
• int32 g - For direct colour, green between 0-255
• int32 b - For direct colour, blue between 0-255
• char8 index - For indexed modes, the colour index to use for clearing. For direct colour modes, the alpha value!

Hermes_ClearerClear returns any non-zero value on success. If zero is returned, the clearing has failed, most of the time because the handle you have passed was invalid.