API description
---------------

Here's a short outline of the API. As it's OpenGL(tm) compatible,
only the differences to this API is outlined. If in doubt, have a
look at the source code and the demos. Sorry if this is not really
worth to be called "documentation", but our time right now is too
tight to work on anything larger.

The following functions are implemented:

glAlphaFunc            glFrontFace              glScaled            glNormal3f
glBegin                glFrustum                glScalef            glTexEnvi
glEnd                  glGenTextures            glScissor           glTexEnvf
glTexGeni              glGetError               glShadeModel        glTexEnviv
glBindTexture          glGetString              glTexCoord2f        glTexEnvfv
glBlendFunc            glHint                   glTexCoord2fv       glTexParameteri
glClear                glLoadIdentity           glTexImage2D        glTexParameterf
glClearColor           glLoadMatrixf            glTexSubImage2D     glTexParameteriv
glClearDepth           glLoadMatrixd            glTranslated        glTexParameterfv
glColorTable           glMatrixMode             glTranslatef
glCullFace             glMultMatrixd            glViewport
glDeleteTextures       glMultMatrixf            glVertex4f
glDepthFunc            glOrtho                  glVertex2f
glDepthMask            glPixelStorei            glVertex2i
glEnable               glPixelStoref            glVertex3f
glDisable              glPolygonMode            glVertex3fv
glDrawBuffer           glPushMatrix             glDepthRange
glFinish               glPopMatrix              glColor4f
glFlush                glReadPixels             glColor4fv
glFogf                 glRotated                glColor3f
glFogfv                glRotatef                glColor3fv
glFogi                                          glColor4ub
                                                glColor4ubv
                                                glColor3ub
                                                glColor3ubv


gluLookAt
gluPerspective


These functions are more or less compatible. You  should  have  a
look at the source code for determining what's really supported.



These functions are MiniGL specific:

void MGLInit()
void MGLTerm()
    MGLInit should be the first MiniGL function called, while MGLTerm should be the last.
    They Open/Close required libraries...



void *mglCreateContext(int offx, int offy, int w, int h);

    This function creates a rendering context for MiniGL. Currently, there can be only
    one context per application.

    offx, offy - currently ignored, set to 0 for future compatibility.
    w,h        - dimensions of the display to be opened.

    The function returns 0 if it failed, and non-zero if successfull. The return value
    is a pointer to the created context, which is private, and currently of no use, anyway.



void * mglCreateContextFromID(GLint id, GLint *w, GLint *h);

    This function creates a context, with id being a valid display mode for Warp3D.

    id  - display mode (see mglGetSupportedScreenModes for obtaining it). It's either
          an Amiga display mode, MGL_SM_WINDOWMODE (indicating "use window mode"), or
          MGL_SM_BESTMODE (indicating "use best mode").
    w,h - pointers to variables that are fille with the actual dimensions of the display.

    The functions return value are equal to that of mglCreateContext.



void mglDeleteContext();

    Deletes a context previously created by mglCreateContex/mglCreateContextFromID.



void mglResizeContext(GLsizei width, GLsizei height);

    Resize the drawing area. The screen is closed and opened again with the
    new dimension.
    Note: This function currently only resizes a full screen context.

    width, height - new dimensions for the display.



void mglEnableSync(GLboolean enable);

    Enables or disables vertical syncing of the display.

    enable - either GL_TRUE, or GL_FALSE.

    This function takes effect immediatly, and can be called before or after creating
    of the context.



void mglWriteShotPPM(char *filename);

    Write the contents of the current front buffer to a PPM file.

    filename - name of the file to write to.



void mglTexMemStat(GLint *Current, GLint *peak);

    This functions requests information about the texture memory usage.

    Current - pointer to a GLint that will be filled with the amount of texture
              memory currently in use.
    Peak    - pointer to a GLint that will be filled with the highest amount of
              texture memory that was allocated at one time.



GLboolean mglLockDisplay(void);

    This function locks the hardware for rendering, and must be called before
    rendering anything. This function is not needed if the lock mode is set
    to SMART (see the discussion of mglLockMode for an explanation).

    The return value is a GLboolean, with GL_TRUE meaning the lock has succeeded,
    and GL_FALSE otherwise.



void mglUnlockDisplay(void);

    A lock obtained with mglLockDisplay or mglLockBack (see below) must be released
    once the frame is finished. mglUnlockDisplay will take care of that. Note that
    it is safe to call this function without a lock, or with SMART lock enabled.



GLboolean mglLockBack(MGLLockInfo *info);

    Gives access to the back buffer. The structure pointed to by info is fille with the
    appropriate values, and GL_TRUE is return when the lock succeeded, GL_FALSE otherwise.
    If the current lock mode (see mglLockMode) is MANUAL, you'll have to unlock yourself.

    info - pointer to a structure to be filled (see include/mgl/modes.h)



void mglLockMode(GLenum lockMode);

    Defines the way display locking is done. Currently, there are two mechanisms:
    MGL_LOCK_MANUAL - You must perform locking yourself (see mglLockDisplay/mglUnlockDisplay)
    MGL_LOCK_SMART  - Locking is performed automatically. This is the save method, as the
                      lock is not kept more than 1/20th second. Per-frame-locking may,
                      at higher resolutions, stall the system, possibily causing a dead-lock.

    lockMode - one of the above



void mglMainLoop(void);

    MiniGL supports a mechanism similar to X or glut: you have a library-provided
    main loop, and define some callback functions that are called on special events.
    This function starts the main loop. It will not terminate, unless mglExit is
    called.

    You can set event handlers with the functions mglKeyFunc, mglMouseFunc, and mglIdelFunc.
    To terminate the loop, use mglExit.



void mglKeyFunc(KeyHandlerFn k);

    This function sets the key handler function.

    k - Pointer to a KeyHandlerFn function. KeyHandlerFn is defined as
        void (*KeyHandlerFn)(char key); The key function will get a Vanilla key
        as it's argument.



void mglMouseFunc(MouseHandlerFn m);

    Sets the mouse handler function.

    m - Pointer to a MoseHandlerFn. The prototype for the handler function
        is void (*MouseHandlerFn)(GLint x, GLint y, GLbitfield buttons);



void mglIdleFunc(IdleFn *i);

    The name is misleading, this function is called every time the main loop
    makes an iteration. This function can be used for displaying one frame.

    i - Pointer to a function to be called every frame. The prototype is
        void (*IdleFn)(void);


void mglExit(void);

    Calling this function in any of the callback functions will terminate
    the main loop, causing mglMainLoop to return.



void mglSwitchDisplay(void);

    When called, mglSwitchDisplay causes the current drawing area to be made visible.
    Depending on sync state, this function may wait for a vertical blanking




void *mglGetWindowHandle(void);

    Returns the window handle which is used for rendering. This function provides
    a way for more complicated applications that do not want to use the mglMainLoop
    interface. The window has no IDCMP flags set, use ModifyIDCMP to actually
    get something.

    The return value is a struct Window *.



GLint mglGetSupportedScreenModes(MGLScreenModeCallback CallbackFn);

    This function can be used to get all available screen modes supported by MiniGL.
    It calls the callback function with every screenmode.

    CallbackFn - Pointer to a function for enumerating the screen modes.
                 The function has the following prototype:
                 GLboolean ScreenModeCallback(MGLScreenMode *mode);
                 (The MGLScreenMode is defined in include/mgl/modes.h).
                 mglGetSupportedScreenModes will continue feeding modes to
                 the callback until it runs out of modes, or the callback
                 returns GL_TRUE, indicating it has found a suitable mode.

    The return value is the mode id which was accepted by the callback function,
    or MGL_SM_BESTMODE.



void mglChooseWindowMode(GLboolean window_mode);

    This function is called before creating a context. It can tell MiniGL to
    open it's display as a window on the workbench.

    window_mode - GL_TRUE makes the display a window on the workbench,
                  GL_FALSE opens a screen.



void mglChooseVertexBufferSize(GLint size);

    MiniGL doesn't render it's primitives at one. It collects everything between
    glBegin and glEnd, and renders with the glEnd call. The buffer for the
    vertex data is called the vertex buffer. As this is created with the
    context, it must be set before creating it.

    size - number of entries in the vertex buffer. Default is 30.
           Set this to a value equal to, or larger than your "longest"
           primitive, i.e. the biggest amount of glVertex calls at between
           glBegin and glEnd.

    Example:

        glBegin(GL_TRIANGLES);
            glVertex3f(1.0, 1.0, 1.0);
            glColor3f(0.1, 1.0, 0.2);

            glVertex3f(1.0, 1.0, 0.0);
            glColor3f(0.1, 1.0, 1.0);

            glVertex3f(1.0, 0.0, 1.0);
            glColor3f(0.1, 0.0, 0.2);
        glEnd();

        There are three glVertex calls (the glColor calls do not affect this. These
        just set the current vertex's color).