header_docs.txt

PortableGL 0.101.0 MIT licensed software renderer that closely mirrors OpenGL 3.x
portablegl.com
robertwinkler.com

Do this:
    #define PORTABLEGL_IMPLEMENTATION
before you include this file in *one* C or C++ file to create the implementation.

If you plan on using your own 3D vector/matrix library rather than crsw_math
that is built into PortableGL and your names are the standard glsl vec[2-4],
mat[3-4] etc., define PGL_PREFIX_TYPES too before including portablegl to
prefix all those builtin types with pgl_ to avoid the clash. Note, if
you use PGL_PREFIX_TYPES and write your own shaders, the type for vertex_attribs
is also affected, changing from vec4* to pgl_vec4*.

You can check all the C++ examples and demos, I use my C++ rsw_math library.

// i.e. it should look like this:
#include ...
#include ...
#include ...
// if required
#define PGL_PREFIX_TYPES

#define PORTABLEGL_IMPLEMENTATION
#include "portablegl.h"

You can define PGL_ASSERT before the #include to avoid using assert.h.
You can define PGL_MALLOC, PGL_REALLOC, and PGL_FREE to avoid using malloc,
realloc, and free.
You can define PGL_MEMMOVE to avoid using memmove.

However, even if you define all of those before including portablegl, you
will still be using the standard library (math.h, string.h, stdlib.h, stdio.h
stdint.h, possibly others). It's not worth removing PortableGL's dependency on
the C standard library as it would make it far larger and more complicated
for no real benefit.


QUICK NOTES:
    Primarily of interest to game/graphics developers and other people who
    just want to play with the graphics pipeline and don't need peak
    performance or the the entirety of OpenGL or Vulkan features.

    For textures, GL_UNSIGNED_BYTE is the only supported type.
    Internally, GL_RGBA is the only supported format, however other formats
    are converted automatically to RGBA unless PGL_DONT_CONVERT_TEXTURES is
    defined (in which case a format other than GL_RGBA is a GL_INVALID_ENUM
    error). The argument internalformat is ignored to ease porting.

    Only GL_TEXTURE_MAG_FILTER is actually used internally but you can set the
    MIN_FILTER for a texture. Mipmaps are not supported (GenerateMipMap is
    a stub and the level argument is ignored/assumed 0) and *MIPMAP* filter
    settings are silently converted to NEAREST or LINEAR.

    The framebuffer format is a compile time setting which defaults
    to 32-bit RGBA memory order, though PGL supports any 32 or 16 bit pixel format
    as long as the appropriate macros are defined.
    Several variants are predefined for easy use, named for the integer order
    not the memory order:

        PGL_RGBA32: RGBA memory order on MSB architecture
        PGL_ABGR32: RGBA memory order on LSB architecture, default
        PGL_ARGB32/PGL_BGRA32: Two other common 32-bit formats
        PGL_RGB565/PGL_BGR565: Very common 16 bit formats
        PGL_RGBA5551/PGL_ABGR1555: Less common 16 bit formats

    Search PGL for those macros to see how to set up the controlling macros
    for other formats; it's pretty self explanatory though I may try to improve
    it in the future.

    The depth and stencil buffer defaults to a combined buffer with the high
    24 bits used for the depth value and the low 8 bits used for the stencil.
    This format is called PGL_D24S8 internally. The only other format supported
    is a 16 bit depth buffer and a separate 8-bit buffer for the stencil. This
    is selected by defining PGL_D16 before including PGL.

    If you define PGL_D16, you may also define PGL_NO_STENCIL to disable the
    stencil buffer entirely to save a bit more memory. However if you define
    PGL_NO_STENCIL you must define PGL_D16 as it makes no sense with
    the default PGL_D24S8.

    Lastly, you can define PGL_NO_DEPTH_NO_STENCIL which will of course
    disable both the depth and stencil buffers entirely.

    There are several predefined configuration depending on how much memory
    you want to/can use that select settings for the framebuffer formats and
    the vertex scratch space size:

    PGL_TINY_MEM: RGB565, D16, NO_STENCIL, 4 vertex attribs, 80 KB scratch space
    PGL_SMALL_MEM: Same as TINY but 800 KB scratch space
    PGL_MED_MEM: RGB565, 4 vertex attribs, 1.6 MB scratch space
    default: ABGR32, D24S8, 8 vertex attribs, 16 MB scratch space

    Obviously most of the time the default is fine, and if none of the
    presets match what you want you can mix and match and adjust any of
    the finer grained options individually, but don't define a preset *and*
    define individual settings as that will cause problems.


DOCUMENTATION
=============

Any PortableGL program has roughly this structure, with some things
possibly declared globally or passed around in function parameters
as needed:

    #define WIDTH 640
    #define HEIGHT 480

    // shaders are functions matching these prototypes
    void smooth_vs(float* vs_output, vec4* vertex_attribs, Shader_Builtins* builtins, void* uniforms);
    void smooth_fs(float* fs_input, Shader_Builtins* builtins, void* uniforms);

    typedef struct My_Uniforms {
        mat4 mvp_mat;
        vec4 v_color;
    } My_Uniforms;

    pix_t* backbuf = NULL;
    glContext the_context;

    if (!init_glContext(&the_context, &backbuf, WIDTH, HEIGHT)) {
        puts("Failed to initialize glContext");
        exit(0);
    }

    // interpolation is an array with an entry of PGL_SMOOTH, PGL_FLAT or
    // PGL_NOPERSPECTIVE for each float being interpolated between the
    // vertex and fragment shaders.  Convenience macros are available
    // for 2, 3, and 4 components, ie
    // PGL_FLAT3 expands to PGL_FLAT, PGL_FLAT, PGL_FLAT

    // the last parameter is whether the fragment shader writes to
    // gl_FragDepth or discard. When it is false, PGL may do early
    // fragment processing (scissor, depth, stencil etc) for a minor
    // performance boost but canonicaly these happen after the frag
    // shader
    GLenum interpolation[4] = { PGL_SMOOTH4 };
    GLuint myshader = pglCreateProgram(smooth_vs, smooth_fs, 4, interpolation, GL_FALSE);
    glUseProgram(myshader);

    // v_color is not actually used since we're using per vert color
    My_Uniform the_uniforms = { IDENTITY_MAT4() };
    pglSetUniform(&the_uniforms);

    // Your standard OpenGL buffer setup etc. here
    // Like the compatibility profile, we allow/enable a default
    // VAO.  We also have a default shader program for the same reason,
    // something to fill index 0.
    // see implementation of init_glContext for details

    while (1) {

        // standard glDraw calls, switching shaders etc.

        // use backbuf however you want, whether that's blitting
        // it to some framebuffer in your GUI system, or even writing
        // it out to disk with something like stb_image_write.
    }

    free_glContext(&the_context);

    // compare with equivalent glsl below
    void smooth_vs(float* vs_output, vec4* vertex_attribs, Shader_Builtins* builtins, void* uniforms)
    {
        ((vec4*)vs_output)[0] = vertex_attribs[1]; //color

        builtins->gl_Position = mult_mat4_vec4(*((mat4*)uniforms), vertex_attribs[0]);
    }

    void smooth_fs(float* fs_input, Shader_Builtins* builtins, void* uniforms)
    {
        builtins->gl_FragColor = ((vec4*)fs_input)[0];
    }

    // note smooth is the default so this is the same as smooth out vec4 vary_color
    // https://www.khronos.org/opengl/wiki/Type_Qualifier_(GLSL)#Interpolation_qualifiers
    uniform mvp_mat
    layout (location = 0) in vec4 in_vertex;
    layout (location = 1) in vec4 in_color;
    out vec4 vary_color;
    void main(void)
    {
        vary_color = in_color;
        gl_Position = mvp_mat * in_vertex;
    }

    in vec4 vary_color;
    out vec4 frag_color;
    void main(void)
    {
        frag_color = vary_color;
    }

    // You might also want to resize the framebuffer if your window is resizable
    // instead of just letting your GUI system scale the output in which case when
    // you handle a resize event you would do something like this:

    pglResizeFramebuffer(new_width, new_height);
    backbuf = (pix_t*)pglGetBackBuffer();
    glViewport(0, 0, new_width, new_height);
    // anything else you need for your particular GUI/windowing system here

    // alternatively, if your backbuffer (ie color buffer) is changing
    // ie, you're switching between rendering to a texture and the normal
    // backbuffer, you would call pglSetBackBuffer() and pglSetTexBackBuffer()
    // as needed:

    pglSetTexBackBuffer(tex_handle);
    pglSetBackBuffer(backbuf, width, height);

    // A few important things to note about these functions:
    // 1. The framebuffer pixel format must be 32-bit RGBA (this is the default
    //    PGL_ABGR32 aka RGBA32 on LSB) if you want to do render-to-texture
    //    because that's the only texture format supported. I have ideas for loosening
    //    this restriction at least a little in the future.
    //
    // 2. Neither function changes the the depth/stencil buffers so assuming
    //    you have depth and/or stencil, the only way to use these safely is
    //    to make sure the texture is the same dimensions or you provide the same
    //    width and height to pglSetBackBuffer().
    //
    // 3. PGLSetBackBuffer() does not change the ownership of the framebuffer memory,
    //    nor does it free the existing framebuffer even if it did own it.
    //    If the backbuffer was not user owned before the call, it will still
    //    not be after the call. If you didn't already get a pointer to the pixels
    //    (via pglGetBackBuffer() for example) you will have created a memory leak.
    //    Though this behavior may seem counter-intuitive, it is to support the most
    //    common use case more easily, where you let PGL handle the allocations and
    //    resizing but you hold a pointer so you can switch back and forth.
    //
    // 4. PGLSetTexBackBuffer() does change the owership of the framebuffer
    //    to match the texture used. Since this is almost always PGL owned
    //    it is usually a non-issue.
    //
    //  See the lesson16 example for examples of these functions in action.

That's basically it.  There are some other non-standard features like
pglSetInterp that lets you change the interpolation of a shader
whenever you want.  In real OpenGL you'd have to have 2 (or more) separate
but almost identical shaders to do that.


ADDITIONAL CONFIGURATION
========================

We've already mentioned several configuration macros above but here are
all of the non-framebuffer/memory related ones:

PGL_UNSAFE
    This replaces the old portablegl_unsafe.h
    It turns off all error checking and debug message/logging the same way
    NDEBUG turns off assert(). By default PGL is a GL_DEBUG_CONTEXT with
    GL_DEBUG_OUTPUT on and a default callback function printing to stdout.
    You can use Enable/Disable and DebugMessageCallback to turn it on/off
    or use your own callback function like normal. However with PGL_UNSAFE
    defined, there's nothing compiled in at all so I would only use it
    when you're pushing for every ounce of perf.

PGL_PREFIX_TYPES
    This prefixes the standard glsl types (and a couple other internal types)
    with pgl_ (ie vec2 becomes pgl_vec2)

PGL_ASSERT
PGL_MALLOC/PGL_REALLOC/PGL_FREE
PGL_MEMMOVE
    These overrride the standard functions of the same names

PGL_DONT_CONVERT_TEXTURES
    This makes passing PGL a texture with a format other than GL_RGBA an error.
    By default other types are automatically converted. You can perform the
    conversion manually using the function convert_format_to_packed_rgba().
    The included function convert_grayscale_to_rgba() is also useful,
    especially for font textures.

PGL_PREFIX_GLSL or PGL_SUFFIX_GLSL
    These replace PGL_EXCLUDE_GLSL. Since PGL depends on at least a few
    glsl functions and potentially more in the future it doesn't make
    sense to exclude GLSL entirely, especially since they're all inline so
    it really doesn't save you anything in the final executable.
    Instead, using one of these two macros you can change the handful of
    functions that are likely to cause a conflict with an external
    math library like glm (with a using declaration/directive of course).
    So smoothstep() would become either pgl_smoothstep() or smoothstepf(). So far it is less than
    10 functions that are modified but feel free to add more.

PGL_HERMITE_SMOOTHING
    Turn on hermite smoothing when doing linear interpolation of textures.
    It is not required by the spec and it does slow it down but it does
    look smoother so it's worth trying if you're curious. Note, most
    implementations do not use it.

PGL_BETTER_THICK_LINES
    If defined, use a more mathematically correct thick line drawing algorithm
    than the one in the official OpenGL spec.  It is about 15-17% slower but
    has the correct width. The default draws exactly width pixels in the
    minor axis, which results in only horizontal and vertical lines being
    correct. It also means the ends are not perpendicular to the line which
    looks worse the thicker the line.  The better algorithm is about what is
    specified for GL_LINE_SMOOTH/AA lines except without the actual
    anti-aliasing (ie no changes to the alpha channel).

PGL_DISABLE_COLOR_MASK
    If defined, color masking (which is set using glColorMask()) is ignored
    which provides some performance benefit though it varies depending on
    what you're doing.

PGL_EXCLUDE_STUBS
    If defined, PGL will exclude stubs for dozens of OpenGL functions that
    make porting existing OpenGL projects and reusing existing OpenGL
    helper/library code with PortableGL much easier.  This might make
    sense to define if you're starting a PGL project from scratch.

PGL_ENABLE_CLAMP_TO_BORDER
    By default it's ignored and treated the same as CLAMP_TO_EDGE because
    I can only think of two ways to implement it. The first way was to
    manually add a 1 pixel border around textures which was far more
    painful and ugly that it sounds to make work and means I can't have
    mapped texture data (ie pglTexImage2D that uses the pointer passed in)
    as well as making any future render to texture functionality more complicated.
    Th second way is with a bunch of extra if statements in the texture sampling
    code which slows down all accesses regardless of if they're using a border
    or not. So it's off by default and you can turn it on with this macro.

There are also several predefined maximums which you can change.
However, considering the performance limitations of PortableGL, the defaults
are probably more than enough, and in fact you might want to decrease PGL_MAX_VERTICES
and GL_MAX_VERTEX_ATTRIBS to save memory, see PGL memory presets in QUICK_NOTES above.

MAX_DRAW_BUFFERS, MAX_COLOR_ATTACHMENTS aren't used since those features aren't implemented.
PGL_MAX_VERTICES refers to the number of output vertices of a single draw call.

#define GL_MAX_VERTEX_ATTRIBS 8
#define GL_MAX_VERTEX_OUTPUT_COMPONENTS (4*GL_MAX_VERTEX_ATTRIBS)
#define GL_MAX_DRAW_BUFFERS 4
#define GL_MAX_COLOR_ATTACHMENTS 4

#define PGL_MAX_VERTICES 500000
#define PGL_MAX_ALIASED_WIDTH 2048.0f
#define PGL_MAX_TEXTURE_SIZE 16384
#define PGL_MAX_3D_TEXTURE_SIZE 8192
#define PGL_MAX_ARRAY_TEXTURE_LAYERS 8192

MIT License
Copyright (c) 2011-2025 Robert Winkler
Copyright (c) 1997-2025 Fabrice Bellard (clipping code from TinyGL)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.