git.mutantstargoat.com Git - miniglut/blob - README.md

   1 MiniGLUT
   2 ========
   3
   4 ![logo](http://nuclear.mutantstargoat.com/sw/miniglut/img/miniglut_logo_sm_alpha.png)
   5
   6 ![GNU/Linux build status](https://github.com/jtsiomb/miniglut/actions/workflows/build_gnulinux.yml/badge.svg)
   7 ![Windows MinGW build status](https://github.com/jtsiomb/miniglut/actions/workflows/build_win_mingw.yml/badge.svg)
   8 ![Windows MSVC6 build status](https://github.com/jtsiomb/miniglut/actions/workflows/build_win_msvc6.yml/badge.svg)
   9
  10 MiniGLUT is a subset of GLUT (or more precisely a subset of FreeGLUT)
  11 implemented in a single C source file, without any non-essential dependencies,
  12 not even the C library.
  13
  14 You can use MiniGLUT by simply dropping two files: `miniglut.h` and `miniglut.c`
  15 into your project source tree, or by building MiniGLUT as a static library and
  16 linking with it.
  17
  18 MiniGLUT does not intend to replace a full GLUT library, like FreeGLUT, for
  19 hacking small to medium OpenGL programs. The purpose of MiniGLUT is to
  20 potentially replace a full GLUT library when it's time for release, in order to
  21 minimize runtime dependencies of the resulting binary.
  22
  23 A second reason to use MiniGLUT is to ease porting of UNIX OpenGL programs to
  24 Windows, especially when using the microsoft compiler, where setting up and
  25 linking with a proper 3rd-party library is an ordeal in itself.  Even more so if
  26 you decide to statically link, at which point you need to deal with the whole
  27 "MSVC runtime" chaos. Even if you decide to link MiniGLUT as a static library,
  28 instead of dropping it in your code, it still won't present any MSVC runtime
  29 compatibility issues, since it doesn't call any C library functions whatsoever.
  30
  31 Download
  32 --------
  33 Latest release (v0.5):
  34   - https://github.com/jtsiomb/miniglut/releases/download/v0.5/miniglut-0.5.tar.gz
  35   - https://github.com/jtsiomb/miniglut/releases/download/v0.5/miniglut-0.5.zip
  36
  37 Both archives are identical, choose whichever is more convenient.
  38
  39 Source repository (git):
  40   - https://github.com/jtsiomb/miniglut
  41
  42 Build
  43 -----
  44 Under X11 MiniGLUT depends only on Xlib and OpenGL. Therefore to build a program
  45 using MiniGLUT you'll need to link with `-lX11 -lGL`.
  46
  47 Under Windows MiniGLUT depends only on OpenGL, GDI and winmm. Therefore to build
  48 a program using MiniGLUT you'll need to link with `-lopengl32 -lgdi32 -lwinmm`.
  49 When building with MSVC, linking with the correct libraries is taken care by
  50 pragmas in the header file. If you wish to avoid the winmm dependency, define
  51 `MINIGLUT_NO_WINMM`.
  52
  53 To avoid calling C library functions, MiniGLUT uses inline assembly code for
  54 system calls and trigonometric operations. This makes the default build
  55 incompatible with non-x86 systems, and with MSVC x64 builds. If you don't mind
  56 linking with the C library, you can define `MINIGLUT_USE_LIBC` to lift these
  57 limitations.
  58
  59 License
  60 -------
  61 Copyright (C) 2020-2022 John Tsiombikas <nuclear@member.fsf.org>
  62
  63 MiniGLUT is free software. Feel free to use, modify and/or redistribute it,
  64 under the terms of the GNU General Public License v3, or at your option any
  65 newer version published by the Free Software Foundation. See COPYING for
  66 details.
  67
  68 The intention is not to dictate a specific free software license (GPL) but to
  69 shut the door to proprietary programs. If you want to use MiniGLUT in a free
  70 software project with an incompatible license, contact me and we will figure out
  71 a way to enable that.
  72
  73 To learn more about GPL-incompatible free software licenses where this might
  74 be an issue, see:
  75 https://www.gnu.org/licenses/license-list.en.html#GPLIncompatibleLicenses
  76
  77 Known Issues
  78 ------------
  79 MiniGLUT being a subset of GLUT, is missing a number of features. Some of them
  80 on purpose to keep it minimal, and some of them because I didn't happen to use
  81 them in a program I wanted to link with MiniGLUT yet.
  82
  83 Missing GLUT features:
  84  - The only supported systems are: UNIX with X11 (GLX), and Windows (WGL).
  85  - Multiple windows.
  86  - Subwindows.
  87  - Overlays.
  88  - Game mode (video mode switching).
  89  - Menus.
  90  - Font rendering.
  91  - Some of the primitives.
  92  - Buttons and Dials callbacks.
  93  - Tablet callbacks.
  94  - Spaceball callbacks are only implemented on UNIX/X11.
  95  - Timer callback.
  96
  97 Missing FreeGLUT features:
  98  - Mobile callbacks.
  99  - Context version and profile selection and other context flags.
 100  - Window close actions.
 101  - Multi-touch/multi-pointer callbacks.
 102  - User-pointer callbacks.
 103  - Joystick callbacks.
 104  - More missing primitives.
 105
 106 If wish to let me know how much you need one of the missing features, or even
 107 better if you are volunteering to implement it yourself, send me an email at:
 108 nuclear@member.fsf.org
 109
 110 Only plain-text emails, hard-wrapped at 72 columns will be accepted.