Sphere Video Driver Specification
Chad Austin
2000.02.01


Sphere video drivers are special DLLs in the sphere/video/ directory.  In
order for a DLL to qualify as a video driver, it must contain every function
listed in this specification.  Each function uses the standard calling
convention (__stdcall).


Drivers should give the window that is passed into InitVideoDriver() focus so
that Sphere input still behaves correctly.


== Data types (byte alignment) ===============================================

typedef void* IMAGE;
typedef int bool;

typedef struct
{
  byte red;
  byte green;
  byte blue;
  byte alpha;
} RGBA;

typedef struct
{
  const char* name;
  const char* author;
  const char* date;
  const char* version;
  const char* description;
} DRIVERINFO;


== Functions =================================================================

void  GetDriverInfo(DRIVERINFO* driverinfo)
void  ConfigureDriver(HWND parent)

bool  InitVideoDriver(HWND window, int screen_width, int screen_height)
bool  CloseVideoDriver(void)

bool  FlipScreen(void)
bool  SetClippingRectangle(int x, int y, int w, int h)
bool  GetClippingRectangle(int* x, int* y, int* w, int* h);
bool  ApplyColorMask(RGBA mask)

IMAGE CreateImage(IMAGE image, int width, int height, RGBA* pixels)
IMAGE GrabImage(IMAGE image, int x, int y, int width, int height)
bool  DestroyImage(IMAGE image)
bool  BlitImage(IMAGE image, int x, int y)
int   GetImageWidth(IMAGE image)
int   GetImageHeight(IMAGE image)
RGBA* LockImage(IMAGE image)
void  UnlockImage(IMAGE image)
void  DirectBlit(int x, int y, int w, int h, RGBA* pixels, int method)
void  DirectGrab(int x, int y, int w, int h, RGBA* pixels)


------------------------------------------------------------------------------

void GetDriverInfo(DRIVERINFO* driverinfo)

  Retrieves general information about the driver.  It grabs five informational
  strings along.

  driverinfo - pointer to DRIVERINFO struct that contains driver information
    after function is called

------------------------------------------------------------------------------

void ConfigureDriver(HWND parent)

  Opens a dialog box which allows user to configure driver.

  parent - handle of parent window

------------------------------------------------------------------------------

bool InitVideoDriver(HWND window, int screen_width, int screen_height)

  Initializes the driver with a specified resolution.  It must be called
  before all other functions except GetDriverInfo() and ConfigureDriver().

  window        - handle of Sphere window
  screen_width  - requested screen width
  screen_height - requested screen height

  returns: true on success, false on failure

------------------------------------------------------------------------------

bool CloseVideoDriver(void)

  Shuts down the driver.  No other functions except InitVideoDriver() may be
  called after it.

  returns: true on success, false on failure

------------------------------------------------------------------------------

void FlipScreen(void)

  Copies the internal backbuffer to the screen.  The backbuffer's contents are
  undetermined after a call to FlipScreen().

------------------------------------------------------------------------------

bool SetClippingRectangle(int x, int y, int w, int h)

  Sets the clipping rectangle.  Functions that modify the screen only affect
  the pixels in the screen rectangle (x, y, x + w, y + h).  The right and
  bottom edges of the rectangle are not affected.

  The default clipping rectangle is (0, 0, screen_width, screen_height).

  returns: true on success, false on failure

------------------------------------------------------------------------------

bool GetClippingRectangle(int* x, int* y, int* w, int* h)

  Retrieves the current clipping rectangle.

  x, y, w, h - locations to store current clipping rectangle in

  returns: true on success, false on failure

------------------------------------------------------------------------------

bool ApplyColorMask(RGBA mask)

  Applies a color mask to the entire backbuffer.  This can be used to put a
  hue on the screen or to fade in and out of any color.

  mask - the color of the mask, using alpha level

  returns: true on success, false on failure

------------------------------------------------------------------------------

IMAGE CreateImage(int width, int height, RGBA* pixels)

  Creates an offscreen buffer that can be blit to the screen.  It is created
  from a linear, rectangular RGBA buffer that is width*height*4 bytes.

  width  - width of image in pixels
  height - height of image in pixels
  data   - linear, rectangular RGBA buffer that contains the image pixels

  returns: handle to new image on success, NULL on failure

------------------------------------------------------------------------------

IMAGE GrabImage(int x, int y, int width, int height)

  Creates an image from data already rendered to the backbuffer.

  image - address of IMAGE struct that returns with grabbed image
  x, y, width, height - coordinates of screen rectangle to create image from

  returns: handle to new image on success, NULL on failure

------------------------------------------------------------------------------

bool DestroyImage(IMAGE image)

  Destroys an image created with CreateImage().  This makes the image invalid
  and it may not be used after DestroyImage() is called.

  image - image handle

  returns: true on success, false on failure

------------------------------------------------------------------------------

bool BlitImage(IMAGE image, int x, int y)

  Draws an image in the backbuffer.

  image - image handle
  x     - x-coordinate of upper-left corner of destination rectangle
  y     - y-coordinate of upper-left corner of destination rectangle

  returns: true on success, false on failure

------------------------------------------------------------------------------

int GetImageWidth(IMAGE image)

  Retrieves the width of an image in pixels.

  image - image handle

  returns: width of image  

------------------------------------------------------------------------------

int GetImageHeight(IMAGE image)

  Retrieves the height of an image in pixels.

  image - image handle

  returns: height of image

------------------------------------------------------------------------------

RGBA* LockImage(IMAGE image)

  Locks an image that has already been created and prepares it for
  post-creation editing.  An image cannot be used between LockImage() and
  UnlockImage() calls.

  image - handle of image to modify

  returns: pointer to pixel data (image_width * image_height) that can be
           modified.

------------------------------------------------------------------------------

void UnlockImage(IMAGE image)

  Puts an image locked with LockImage() back in a usable state.  Every call to
  LockImage() must be matched with a call to UnlockImage().

  image - image handle

------------------------------------------------------------------------------

void DirectBlit(int x, int y, int w, int h, RGBA* pixels, int method)

  Directly draws a pixel buffer directly to the backbuffer without going
  through the image interface.  It renders it using one of three methods.

  x - x-coordinate of upper-left corner of destination rectangle
  y - y-coordinate of upper-left corner of destination rectangle
  w - width of pixel buffer
  h - height of pixel buffer
  pixels - RGBA data
  method -
    0 = do not blit anything
    1 = render image as opaque tile (no alpha data)
    2 = render image using alpha data

------------------------------------------------------------------------------

void DirectGrab(int x, int y, int w, int h, RGBA* pixels)

  Pulls an RGBA pixel buffer from directly off the backbuffer.

  x - x-coordinate of upper-left corner of source rectangle
  y - y-coordinate of upper-left corner of source rectangle
  w - width of pixel buffer
  h - height of pixel buffer
  pixels - pixel buffer

------------------------------------------------------------------------------
