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