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)
bool  ToggleFullscreen(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 CloneImage(IMAGE image)
IMAGE GrabImage(IMAGE image, int x, int y, int width, int height)
void  DestroyImage(IMAGE image)
void  BlitImage(IMAGE image, int x, int y, CImage32::BlendMode blendmode)
void  BlitImageMask(IMAGE image, int x, int y, CImage32::BlendMode blendmode, RGBA mask)
void  TransformBlitImage(IMAGE image, int x[4], int y[4], CImage32::BlendMode blendmode)
void  TransformBlitImageMask(IMAGE image, int x[4], int y[4], CImage32::BlendMode blendmode, 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 DrawPointSeries(VECTOR_INT** points, int length, RGBA color)
void DrawLine(int x[2], int y[2], RGBA color)
void DrawGradientLine(int x[2], int y[2], RGBA colors[2])
void DrawLineSeries(VECTOR_INT** points, int length, RGBA color, int type)
void DrawBezierCurve(int x[4], int y[4], double step, RGBA color, int cubic)
void DrawTriangle(int x[3], int y[3], RGBA color)
void DrawGradientTriangle(int x[3], int y[3], RGBA colors[3])
void DrawPolygon(VECTOR_INT** points, int length, int invert, RGBA color)
void DrawOutlinedRectangle(int x, int y, int w, int h, int size, RGBA color)
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 DrawOutlinedComplex(int r_x, int r_y, int r_w, int r_h, int circ_x, int circ_y, int circ_r, RGBA color, int antialias)
void DrawFilledComplex(int r_x, int r_y, int r_w, int r_h, int circ_x, int circ_y, int circ_r, float angle, float frac_size, int fill_empty, RGBA colors[2])
void DrawGradientComplex(int r_x, int r_y, int r_w, int r_h, int circ_x, int circ_y, int circ_r, float angle, float frac_size, int fill_empty, RGBA colors[3])
void DrawOutlinedEllipse(int x, int y, int rx, int ry, RGBA color)
void DrawFilledEllipse(int x, int y, int rx, int ry, RGBA color)
void DrawOutlinedCircle(int x, int y, int r, RGBA color, int antialias)
void DrawFilledCircle(int x, int y, int r, RGBA color, int antialias)
void DrawGradientCircle(int x, int y, int r, RGBA colors[2], int antialias)


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

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.

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

bool ToggleFullscreen(void)

  Toggles fullscreen by closing the video driver and initializing with the new mode.

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

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 CloneImage(IMAGE image)

  Creates a new image which is a copy of the argument image.

  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, CImage32::BlendMode blendmode)

  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
  blendmode - constant identifying the requested blend mode

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

void BlitImageMask(IMAGE image, int x, int y, CImage32::BlendMode blendmode, RGBA mask)

  Draws a masked image to the backbuffer.

  image - handle
  x, y  - coordinates
  blendmode - constant identifying the requested blend mode
  mask  - color/alpha mask

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

void TransformBlitImage(IMAGE image, int x[4], int y[4], CImage32::BlendMode blendmode)

  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)
  blendmode - constant identifying the requested blend mode

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

void TransformBlitImageMask(IMAGE image, int x[4], int y[4], CImage32::BlendMode blendmode, 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 DrawPointSeries(VECTOR_INT** points, int length, RGBA color)

  Draws a series of points 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 DrawLineSeries(VECTOR_INT** points, int length, RGBA color, int type)

  Draws a series of lines directly to the backbuffer

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

void DrawBezierCurve(int x[4], int y[4], double step, RGBA color, int cubic)

  Draws a Bezier curve 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 DrawPolygon(VECTOR_INT** points, int length, int invert, RGBA color)

  Draws a polygon directly to the backbuffer

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

void DrawOutlinedRectangle(int x, int y, int w, int h, int size, RGBA color)

  Draws an outlined rectangle directly to the backbuffer

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

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

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

void DrawOutlinedComplex(int r_x, int r_y, int r_w, int r_h, int circ_x, int circ_y, int circ_r, RGBA color, int antialias)

  Draws a solid rectangle with a circle cut out directly to the backbuffer

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

void DrawFilledComplex(int r_x, int r_y, int r_w, int r_h, int circ_x, int circ_y, int circ_r, float angle, float frac_size, int fill_empty, RGBA colors[2])

  Draws a solid rectangle with a (fractioned) circle on it directly to the backbuffer

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

void DrawGradientComplex(int r_x, int r_y, int r_w, int r_h, int circ_x, int circ_y, int circ_r, float angle, float frac_size, int fill_empty, RGBA colors[3])

  Draws a solid rectangle with a (fractioned) circle on it directly to the backbuffer

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

void DrawOutlinedEllipse(int x, int y, int rx, int ry, RGBA color)

  Draws an outlined ellipse directly to the backbuffer

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

void DrawFilledEllipse(int x, int y, int rx, int ry, RGBA color)

  Draws a filled ellipse directly to the backbuffer

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

void DrawOutlinedCircle(int x, int y, int r, RGBA color, int antialias)

  Draws an outlined circle directly to the backbuffer

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

void DrawFilledCircle(int x, int y, int r, RGBA color, int antialias)

  Draws a filled circle directly to the backbuffer

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

void DrawGradientCircle(int x, int y, int r, RGBA colors[2], int antialias)

  Draws a gradient circle directly to the backbuffer

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