Sphere Video Driver Specification
Chad Austin
2001.01.05


Sphere video drivers are special DLLs in the sphere/system/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 unsigned char 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)
void  CloseVideoDriver(void)

void  FlipScreen(void)
void  SetClippingRectangle(int x, int y, int w, int h)
void  GetClippingRectangle(int* x, int* y, int* w, int* h)

IMAGE CreateImage(IMAGE image, int width, int height, RGBA* pixels)
IMAGE GrabImage(IMAGE image, int x, int y, int width, int height)
void  DestroyImage(IMAGE image)
void  BlitImage(IMAGE image, int x, int y)
void  BlitImageMask(IMAGE image, int x, int y, RGBA mask)
void  TransformBlitImage(IMAGE image, int x[4], int y[4])
void  TransformBlitImageMask(IMAGE image, int x[4], int y[4], RGBA mask)
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)
void  DirectTransformBlit(int x[4], int y[4], int w, int h, RGBA* pixels)
void  DirectGrab(int x, int y, int w, int h, RGBA* pixels)

void DrawPoint(int x, int y, RGBA color)
void DrawLine(int x[2], int y[2], RGBA color)
void DrawGradientLine(int x[2], int y[2], RGBA colors[2])
void DrawTriangle(int x[3], int y[3], RGBA color)
void DrawGradientTriangle(int x[3], int y[3], RGBA colors[3])
void DrawRectangle(int x, int y, int w, int h, RGBA color)
void DrawGradientRectangle(int x, int y, int w, int h, RGBA colors[4])


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

void GetDriverInfo(DRIVERINFO* driverinfo)

  Retrieves general information about the driver.  Retrieves five informational
  strings.

  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

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

void CloseVideoDriver(void)

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

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

void FlipScreen(void)

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

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

void 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).

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

void 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

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

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

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

void 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

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

void 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

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

void BlitImageMask(IMAGE image, int x, int y, RGBA mask)

  Draws a masked image to the backbuffer.

  image - handle
  x, y  - coordinates
  mask  - color/alpha mask

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

void TransformBlitImage(IMAGE image, int x[4], int y[4])

  Draws a coordinate-translated image to the backbuffer.

  image - image handle
  x     - x coordinates (starts at upper left, clockwise)
  y     - y coordinates (starts at upper left, clockwise)

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

void TransformBlitImageMask(IMAGE image, int x[4], int y[4], RGBA mask)

  TransformBlitImage + BlitImageMask!

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

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)

  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

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

void DirectTransformBlit(int x[4], int y[4], int w, int h, RGBA* pixels)

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

  x = x-coordinates of surface (starts at upper-left, clockwise)
  y = y-coordinates of surface (starts at upper-left, clockwise)
  w = width of pixel buffer
  h = height of pixel buffer
  pixels - RGBA 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

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

void DrawPoint(int x, int y, RGBA color)

  Draws a point directly to the backbuffer.

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

void DrawLine(int x1, int y1, int x2, int y2, RGBA color)

  Draws a line directly to the backbuffer.

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

void DrawGradientLine(int x1, int y1, int x2, int y2, RGBA colors[2])

  Draws a gradient line directly to the backbuffer.

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

void DrawTriangle(int x[3], int y[3], RGBA color)

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

void DrawGradientTriangle(int x[3], int y[3], RGBA colors[3])

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

void DrawRectangle(int x, int y, int w, int h, RGBA color)

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

void DrawGradientRectangle(int x, int y, int w, int h, RGBA colors[4])

  colors - upper left, upper right, lower right, lower left

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