library for cursors and mode setting

/*
 * Platform independent OpenGL interface, with functions for:
 *  - describing supported pixel formats
 *  - allocating/managing image buffers
 *  - allocating/managing visuals and drawing surfaces
 *  - creating/managing rendering contexts
 *  - setting dislay modes
 *  - setting the cursor image/position
 *  - monitor queries
 *  - etc...
 */

#ifndef IGL_H
#define IGL_H


#define IGL_MAJOR_VERSION  0
#define IGL_MINOR_VERSION  0


/*
 * IGL datatypes
 */
typedef char IGLchar;
typedef char IGLbyte;
typedef unsigned char IGLubyte;
typedef short IGLshort;
typedef unsigned short IGLushort;
typedef int IGLint;
typedef unsigned int IGLuint;
typedef float IGLfloat;
typedef unsigned char IGLboolean;
typedef unsigned int IGLenum;
typedef unsigned int IGLbitfield;


/*
 * IGL constants
 */

/* boolean */
#define IGL_FALSE         0x0
#define IGL_TRUE          0x1

/* pixel format channels */
#define IGL_RED           0x1100
#define IGL_GREEN         0x1101
#define IGL_BLUE          0x1102
#define IGL_ALPHA         0x1103
#define IGL_LUMINANCE     0x1104
#define IGL_CR_CB         0x1105
#define IGL_CB_CR         0x1106
#define IGL_COLOR_INDEX   0x1107
#define IGL_DEPTH         0x1108
#define IGL_STENCIL       0x1109
#define IGL_AUX           0x1110

/* pixel format datatypes */
#define IGL_UNSIGNED_INT  0x1000
#define IGL_INT           0x1001
#define IGL_FLOAT         0x1002

/* pixel format targets */
#define IGL_FRAMEBUFFER_BIT 0x1
#define IGL_TEXTURE_BIT     0x2
#define IGL_PBUFFER_BIT     0x4
#define IGL_POINTER_BIT     0x8

/* display mode options */
#define IGL_INTERLACED_BIT  0x8

/* GetString targets */
#define IGL_VERSION       0x1300
#define IGL_VENDOR        0x1301
#define IGL_EXTENSIONS    0x1302
#define IGL_RENDERER      0x1303
#define IGL_LAST_ERROR    0x1304

/* memory map modes */
#define IGL_READ_ONLY     0x1400
#define IGL_WRITE_ONLY    0x1401
#define IGL_READ_WRITE    0x1402



/* limits */
#define IGL_MAX_PIXEL_FORMAT_CHANNELS      4
#define IGL_MAX_PIXEL_FORMATS_PER_VISUAL  16


/**
 * IGLRect:  for specifying clip rects.
 */
typedef struct {
   IGLint x0, y0;  /* inclusive */
   IGLint x1, y1;  /* exclusive */
} IGLRect;


/**
 * IGLPixelFormat:  describes arrangement of pixel bits for an image buffer.
 */
typedef struct {
   IGLenum ChannelType;  /* IGL_INT, IGL_UNSIGNED_INT, or IGL_FLOAT */
   IGLuint BitsPerPixel;
   IGLuint NumChannels;
   IGLenum ChannelName[IGL_MAX_PIXEL_FORMAT_CHANNELS];
   IGLuint ChannelSize[IGL_MAX_PIXEL_FORMAT_CHANNELS];
   IGLuint ChannelShift[IGL_MAX_PIXEL_FORMAT_CHANNELS];
   IGLbitfield Targets;  /* or of IGL_FRAMEBUFFER/TEXTURE/PBUFFER_BIT */
} IGLPixelFormat;


/**
 * IGLVisual:  describes a set of pixelformats for a drawing surface.
 * A typical visual will describe pixel formats for one or two color buffers,
 * a depth buffer, a stencil buffer, etc.
 */
typedef struct {
   IGLuint NumPixelFormats;
   IGLPixelFormat Formats[IGL_MAX_PIXEL_FORMATS_PER_VISUAL];
} IGLVisual;


/**
 * IGLBuffer:  an image buffer (pixels store color or Z or stencil, etc).
 * May be 1D, 2D or 3D (for textures).
 */
typedef struct {
   IGLPixelFormat Format;
   IGLuint Width, Height, Depth;
   IGLbitfield Flags;
   IGLuint RowStride, ImageStride;
   void *Address;         /* address in VRAM */
   void *MappedAddress;   /* address in user space if mapped */
} IGLBuffer;


/**
 * IGLCanvas:  a set of IGBuffers which composes a drawing surface
 * (one or more color buffers, depth buffers, stencil buffers, etc).
 */
typedef struct {
   IGLVisual Visual;
   IGLBuffer Buffer[IGL_MAX_PIXEL_FORMATS_PER_VISUAL];
   IGLuint NumClipRects;
   IGLRect *ClipRects;
} IGLCanvas;


/**
 * IGLContext: a GL rendering context
 */
typedef struct {
   IGLVisual Visual;
   IGLBuffer *CurrentBuffer;
} IGLContext;


/**********************************************************************
 * Pixel format functions.
 */


/**
 * Query if the given pixel format is supported by all the specified targets.
 * <targets> is a bitmask of the IGL_FRAMEBUFFER_BIT, IGL_TEXTURE_BIT, and
 * IGL_PBUFFER_BIT bits.
 * \return IGL_TRUE if supported, IGL_FALSE otherwise.
 */
extern IGLboolean
iglIsSupportedPixelFormat(IGLbitfield targets,
                          const IGLPixelFormat *pixelFormat);

/**
 * Return array of pixel formats supported by all the specified targets.
 * \param targets is a bitmask of the IGL_FRAMEBUFFER_BIT, IGL_TEXTURE_BIT,
 *                and IGL_PBUFFER_BIT bits.
 * \param maxResults indicates the maximum number of results to put into the
 *                   <pixelFormats> array.
 * \return number of pixel formats returned.
 */
extern IGLuint
iglGetSupportedPixelFormats(IGLbitfield targets,
                            IGLuint maxResults, IGLPixelFormat *pixelFormats);



/**********************************************************************
 * Screen functions.
 */


/**
 * Return the number of screens supported by the device.
 * \return number of screens
 */
extern IGLuint
iglGetNumScreens(void);

/**
 * Test if the given display mode is supported.
 * \param pixelFormat pixel format of display mode.
 * \param width width (in pixels) of display mode.
 * \param height height (in pixels) of display mode.
 * \param refreshRate refresh rate (in Hz) of display mode.
 * \param flags various options such as IGL_INTERLACED_BIT.
 * \return IGL_TRUE if suported, IGL_FALSE otherwise
 */
extern IGLboolean
iglIsSupportedDisplayMode(IGLuint screen, const IGLPixelFormat *pixelFormat,
                          IGLuint width, IGLuint height, IGLuint refreshRate,
                          IGLbitfield flags);

/**
 * Set the current display mode (resolution, refresh, etc) for the given
 * screen.
 * \param pixelFormat pixel format of display mode.
 * \param width width (in pixels) of display mode.
 * \param height height (in pixels) of display mode.
 * \param refreshRate refresh rate (in Hz) of display mode.
 * \param flags various options such as IGL_INTERLACED_BIT.
 * \return IGL_TRUE if successful, IGL_FALSE otherwise
 */
extern IGLboolean
iglSetDisplayMode(IGLuint screen, const IGLPixelFormat *pixelFormat,
                  IGLuint width, IGLuint height, IGLuint refreshRate,
                  IGLbitfield flags);

/**
 * Enable (scan-out) the given screen.
 */
extern void
iglEnableScreen(IGLuint screen);

/**
 * Disable (turn off) the given screen.
 */
extern void
iglDisableScreen(IGLuint screen);

/**
 * Specify the region of VRAM to display on the monitor.
 */
extern IGLboolean
iglSetScreenPointer(IGLuint screen, IGLuint start, IGLuint stride);

/**
 * Wait for start of vertical retrace on given screen.
 * Return immediately if the screen is disabled.
 */
extern void
iglWaitRetrace(IGLuint screen);



/**********************************************************************
 * Image buffer functions.
 */

/**
 * Allocate an image buffer (might be color, depth, etc, 1D, 2D or 3D)
 * Initial buffer contents are undefined.
 * XXX will probably need more, similar functions for allocating
 * mipmapped textures.
 * \return new IGLBuffer pointer or NULL if we fail.
 */
extern IGLBuffer *
iglAllocateBuffer(IGLenum target, const IGLPixelFormat *pixelformat,
                  IGLuint width, IGLuint height, IGLuint depth,
                  IGLbitfield flags);

/**
 * Deallocate the given image buffer.
 */
extern void
iglFreeBuffer(IGLBuffer *buffer);

/**
 * Resize the given image buffer.  The buffer contents after resize are
 * undefined.
 * \return IGL_TRUE if successful, IGL_FALSE otherwise
 */
extern IGLboolean
iglResizeBuffer(IGLBuffer *buffer,
                IGLuint width, IGLuint height, IGLuint depth);

/**
 * Map the given image buffer into the caller's address space.
 * \param buffer the image buffer to map
 * \param access one of IGL_READ_ONLY, IGL_WRITE_ONLY, IGL_READ_WRITE.
 * \param size returns the size of the mapped region.
 * \return the mapped address or NULL if we fail.
 */
extern void *
iglMapBuffer(IGLBuffer *buffer, IGLenum access, IGLuint *size);

/**
 * Unmap the given image buffer from the caller's address space.
 */
extern void
iglUnmapBuffer(IGLBuffer *buffer);

/**
 * Bind the given image buffer as a texture image.
 * XXX tentative.
 */
extern void
iglBindTextureBuffer(IGLBuffer *buffer, IGLenum textureTarget,
                     IGLuint textureID, IGLuint textureLevel);



/**********************************************************************
 * Canvas functions.
 */

/**
 * Allocate a new drawing canvas.
 * \param targets a bitmask of IGL_FRAMEBUFFER_BIT, IGL_TEXTURE_BIT,
 *                and IGL_PBUFFER_BIT which indicates how the canvas
 *                might be used.
 *                A canvas that will also be used as a texture source would
 *                specify IGL_TEXTURE_BIT | IGL_PBUFFER_BIT.
 * \return pointer to new IGLCanvas or NULL if we fail.
 */
extern IGLCanvas *
iglAllocateCanvas(IGLbitfield targets, const IGLVisual *visual,
                  IGLuint width, IGLuint height, IGLuint depth,
                  IGLbitfield flags);

/**
 * Deallocate the given drawing canvas.
 */
extern void
iglFreeCanvas(IGLCanvas *canvas);

/**
 * Resize the given canvas.  The buffers' contents after resize are
 * undefined.
 * \return IGL_TRUE if successful, IGL_FALSE otherwise
 */
extern void
iglResizeCanvas(IGLCanvas *canvas,
                IGLuint width, IGLuint height, IGLuint depth);

/**
 * Specify a list of clipping rectangles for rendering into the given
 * canvas.
 */
extern void
iglSetClipList(IGLCanvas *canvas, IGLuint numRects, const IGLRect *rectList);



/**********************************************************************
 * Rendering context functions.
 */

/**
 * Create a new OpenGL rendering context.
 */
extern IGLContext *
iglCreateContext(const IGLVisual *visual, IGLContext *shareList);

/**
 * Destroy the given OpenGL rendering context.
 */
extern void
iglDestroyContext(IGLContext *context);

/**
 * Bind the given rendering context to a read/draw canvas pair for the
 * calling thread.
 * Typically, readCanvas == drawCanvas.
 * \return IGL_TRUE if successful, IGL_FALSE otherwise.
 */
extern IGLboolean
iglMakeCurrent(IGLContext *context,
               IGLCanvas *readCanvas, IGLCanvas *drawCanvas);

/**
 * Return the current IGLContext for the calling thread.
 * \return IGLContext pointer or NULL if no current context.
 */
extern IGLContext *
iglGetCurrentContext(void);

/**
 * Return the current IGLCanvas for drawing for the calling thread.
 * \return IGLCanvas pointer or NULL if no current canvas.
 */
extern IGLCanvas *
iglGetCurrentDrawCanvas(void);

/**
 * Return the current IGLCanvas for reading for the calling thread.
 * \return IGLCanvas pointer or NULL if no current canvas.
 */
extern IGLCanvas *
iglGetCurrentReadCanvas(void);



/**********************************************************************
 * Misc functions.
 */

/**
 * Initialize the IGL driver.
 * XXX any parameters???
 */
extern void
iglInitialize(void);

/**
 * Return string information.
 * \param pname one of IGL_VERSION, IGL_VENDOR, IGL_EXTENSIONS, IGL_RENDERER,
 *              or IGL_LAST_ERROR.
 * \return the string or NULL.  If non-null the first and last characters
 *         will be spaces.
 */
extern IGLchar *
iglGetString(IGLenum pname);

/**
 * Return the address of any IGL or OpenGL function.
 */
extern void *
iglGetProcAddress(const char *functionName);



/**********************************************************************
 * Cursor functions.
 */

/**
 * Return max pointer/sprite size supported on given screen.
 */
extern void
iglGetMaxPointerSize(IGLuint screen, IGLuint *width, IGLuint *height);

/**
 * Set the pointer/sprite image for the given screen.
 */
extern void
iglPointerImage(IGLuint screen, IGLuint width, IGLuint height,
                const IGLPixelFormat *format, const void *image);

/**
 * Show/Hide the pointer/sprite on given screen.
 */
extern void
iglShowPointer(IGLuint screen, IGLboolean visible);

/**
 * Set pointer/sprite's current position.
 */
extern void
iglPointerPosition(IGLuint screen, IGLint x, IGLint y);



/**********************************************************************
 * Colormap (palette) functions.
 */

/**
 * Specify the colormap to use for the given screen when scanning
 * out color indexed framebuffers.
 * \param screen
 * \param type  datatype of colormap values: IGL_UNSIGNED_BYTE, etc
 * \param components  number of components per colortable entry
 * \param size  number of colortable entries (typically 256)
 * \param colormap  the colormap values
 */
extern void
iglSetColormap(IGLuint screen, IGLenum type, IGLuint components,
               IGLuint size, const IGLvoid *colormap);



/**********************************************************************
 * XXX to be determined functions:
 * - monitor info / DDC?
 * - DMA negotiation?
 */




#endif /* IGL_H */