fond.h

Go to the documentation of this file.

#pragma once 

#include <vrvGraphicsUtils/vrvGraphicsUtils.h>


#include <stdint.h>
#include <stdlib.h>

#include <map>

#include <GL/glew.h>

struct stbtt_packedchar;
struct stbtt_fontinfo;
struct fond_extent;

// This enum contains all possible error codes
// that libfond can produce.
// 
// See fond_error
// See fond_error_string
enum FondError {
   // Everything is OK.
   FOND_NO_ERROR,
   // The font file could not be read. Most likely
   // it doesn't exist or the permission is denied.
   FOND_FILE_LOAD_FAILED,
   // An allocation failed, probably due to OOM.
   FOND_OUT_OF_MEMORY,
   // Failed to pack the font into an atlas.
   // This most likely means that the atlas' size
   // is too small.
   FOND_FONT_PACK_FAILED,
   // Failed to parse the font file's information.
   // It's likely that the file you gave was not
   // a TTF.
   FOND_FONT_INIT_FAILED,
   // OpenGL signalled an error. Check stderr for
   // more information.
   FOND_OPENGL_ERROR,
   // The maximum size on fond_load_fit was reached.
   FOND_SIZE_EXCEEDED,
   // A render or compute function was called when
   // the font was not properly loaded yet.
   FOND_NOT_LOADED,
   // The UTF8 string could not be converted as it
   // is malformatted.
   FOND_UTF8_CONVERSION_ERROR,
   // An attempt was made to render/compute a glyph
   // that was not included in the list of glyphs
   // when the font was loaded.
   FOND_UNLOADED_GLYPH,
   // The fond_font struct did contain neither a
   // list of characters nor a list of codepoints.
   FOND_NO_CHARACTERS_OR_CODEPOINTS
};

// This is the primary struct that contains all
// relevant information about a font. You must
// allocate this struct yourself and make sure
// that it is zeroed out before you do anything
// with it.
// Either stack allocate it with ={0}, or use
// calloc. Not zeroing out will land you in a
// world of pain.
//
// See fond_free
// See fond_load
// See fond_load_fit
// See fond_compute
// See fond_compute_u
// See fond_compute_extent
// See fond_compute_extent_u
struct DT_DLL_VRVGRAPHICSUTILS fond_font
{
   fond_font();
   void cleanup();
   void cleanup_fontdata();
   void set_error(FondError code) { m_error_code = code; }

   // Path to the TTF file.
   const char *m_file;
   // The index of the font within the TTF file.
   // You probably don't need to set this.
   int m_index;
   // The vertical font size in pixels. If you
   // render it above this resolution, you'll
   // get a blurry mess.
   float m_vsize;
   // A UTF8 encoded string of characters that
   // this font instance will be able to render.
   // Must be null-terminated.
   const char *m_characters;
   // An array of Unicode codepoints that this
   // font instance will be able to render. Must
   // be null-terminated. This is automatically
   // filled in for you, if it is NULL and the
   // characters field is provided instead.
   int32_t *m_codepoints;
   // The width of the glyph texture atlas.
   unsigned int m_width;
   // The height of the glyph texture atlas.
   unsigned int m_height;
   // How much oversampling should be done.
   // Higher oversampling might improve the
   // quality of the rendering, but will need
   // a much bigger atlas size:
   // width*oversampling,height*oversampling
   unsigned int m_oversample;
   // The OpenGL texture ID for the atlas.
   unsigned int m_atlas;
   // Internal data.
   unsigned char *m_fontdata;
   stbtt_packedchar *m_chardata;
   stbtt_fontinfo *m_fontinfo;
   int m_converted_codepoints;
   int m_allocated_atlas;

   FondError m_error_code;


   // Most functions in this API return an int,
   // which can be ither 1 or 0, with the former
   // representing success and the latter
   // failure. On failure, you should check
   // fond_error to see what went wrong.

   // Free all the data that was allocated
   // into the struct by fond_load*. This
   // will /not/ free the characters array,
   // the file array, or the codepoints array
   // if the codepoints array was not computed
   // by fond_load*. It will also not free the
   // texture atlas if it was not alloced by
   // fond_load*.
   void free_memory();

   // Load the font struct and allocate the
   // necessary OpenGL data. The texture atlas
   // is not allocated if the font's atlas field
   // is already set. It is however always filled
   // via glSubImage2D. The bit depth of the pixel
   // values is only 255, and only the red channel
   // is filled, so a texture with internal format
   // of GL_R8 will be created for you if you
   // don't specify your own.
   // The following fields must be set in the
   // struct:
   //   file
   //   size
   //   width
   //   height
   //   characters or codepoints
   int init();

   // Load the font struct, attempting to fit
   // an atlas automatically. This may not
   // result in the most compact atlas possible.
   // max_size is the maximum size of the width
   // or height that can be reached before it
   // gives up. The following fields must be set
   // in the struct:
   //   file
   //   size
   //   characters or codepoints
   int load_fit(unsigned int max_size);

   // Compute the Vertex Array Object to render
   // the given text. Here, n and vao are output
   // arguments, containing the number of elements
   // and the OpenGL VAO ID respectively.
   // The text must be UTF8 encoded and null-
   // terminated. The VAO packs two arrays, one
   // at location 0 and one at 1, with both being
   // vec2s. The first being the vertex coordinates
   // and the second being the texture coordinates.
   // The vertex coordinates start at 0 and increase
   // in x and y as per the font's size. You are
   // responsible for scaling it as appropriate
   // for your display.
   // The texture coordinates are for the font's
   // atlas texture.
   // The triangles are defined with their vertices
   // in counter-clockwise (CCW) order, meaning
   // that if you apply cull-face, you need to have
   // front-faces be set to CCW, which should be
   // the default.
   // If the text contains a Linefeed character
   // (U+000A) a new line is started automatically
   // by resetting X to 0 and decreasing Y by the
   // necessary height for a new line.
   //
   // The VAO and necessary VBOs are allocated
   // automatically for you and then filled in as
   // per fond_update.
   int compute(char *text, size_t *n, unsigned int *vao);

   // Same as fond_compute, but taking an UTF32
   // encoded string of codepoints and its size.
   int compute_utf(int32_t *text, size_t size, size_t *n, unsigned int *vao);


   int codepoint_index(unsigned int glyph);

   // Update the given vertex buffer and element
   // buffers to contain the necessary data to draw
   // the given text.
   // The EBO must be bound to a VAO as a
   // GL_ELEMENT_ARRAY_BUFFER and the VBO as a
   // GL_ARRAY_BUFFER. The VBO contains GLfloats and
   // the EBO contains GLuints. The VBO packs two
   // distinct values as described in fond_compute.
   // They are stored alternatingly in the buffer,
   // meaning that you should bind the buffer to a
   // VAO like this:
   // 
   // glVertexAttribPointer(0, 2, GL_FLOAT, GL_FALSE, sizeof(float)*4, (GLvoid*)0);
   // glVertexAttribPointer(1, 2, GL_FLOAT, GL_FALSE, sizeof(float)*4, (GLvoid*)(2*sizeof(float)));
   //
   // The data is stored in the buffers using
   // DYNAMIC_DRAW, meaning they should be able to
   // be updated frequently enough.
   //
   // Note that the GL buffer and vertex array
   // bindings are modified by this function. You
   // should thus not expect previously bound values
   // to still be the same after this function
   // returns.
   int update(char *text, size_t *n, unsigned int vbo, unsigned int ebo);

   // Same as fond_update, but taking an UTF32
   // encoded string of codepoints and its size.
   int update_utf(int32_t *text, size_t num_chars, size_t *n, unsigned int vbo, unsigned int ebo, int *width);

   // Compute the extent of the given text.
   // You must allocate the extent struct yourself
   // and make sure it is zeroed out.
   int compute_extent(char *text, fond_extent *extent);

   // Same as fond_compute_extent, but taking an
   // UTF32 encoded string of codepoints and its
   // size.
   int compute_extent_utf(int32_t *text, size_t size, fond_extent *extent);

   int load_file(const char *file, unsigned char **content);

};

// This struct allows for convenience in
// rendering, as it will render text for you
// into a texture, which you can then render
// like any other. Thus you won't need to
// handle the actual rendering logic yourself.
//
// See fond_free_buffer
// See fond_load_buffer
// See fond_render
// See fond_render_u
struct DT_DLL_VRVGRAPHICSUTILS fond_buffer
{
   fond_buffer() :
      myTexture2dID(0),
      myTexture3dID(0),
      myWidth(0),
      myHeight(0),
      myProgram(0),
      myFrameBuffer(0),
      myVao(0),
      myVbo(0),
      myEbo(0),
      m_error_code(FOND_NO_ERROR)
   {
      ;
   }

   void cleanup();
   void set_error(FondError error) { m_error_code = error; }

   // Free all the data that was allocated
   // into the struct by fond_load_buffer. This
   // will /not/ free the font struct.
   void free_buffer();

   // Load the buffer struct and allocate the
   // necessary OpenGL data.
   // The following fields must be set in the
   // struct:
   //   font
   //   width
   //   height
   int load_buffer();

   // Pointer to the font that it renders.
   fond_font *font;
   // The OpenGL texture ID to which this
   // buffer renders to.
   // NOT OWNED
   unsigned int myTexture2dID;
   unsigned int myTexture3dID;
   // The width of the texture.
   unsigned int myWidth;
   // The height of the texture.
   unsigned int myHeight;
   // Internal data.
   unsigned int myProgram;
   unsigned int myFrameBuffer;
   unsigned int myVao;
   unsigned int myVbo;
   unsigned int myEbo;
   FondError m_error_code;
};

// This struct contains information about
// the extents of a text.
//
// See fond_compute_extent
// See fond_compute_extent_u
struct fond_extent {
   // How far to the left the text extends
   // from zero.
   float l;
   // How far to the right the text extends
   // from zero.
   float r;
   // How far up the text extends from its
   // baseline.
   float t;
   // How far down the text extends from
   // its baseline.
   float b;
   // The gap between lines of the text.
   float gap;
};

// Render the given text to the buffer's
// texture. The text will be rendered at the
// given offset, with x and y being in pixels.
// color can be either 0 for white text, or
// an array of four floats, representing RGBA
// of the text's colour in that order.
DT_DLL_VRVGRAPHICSUTILS int fond_render(fond_buffer *buffer, const char *text, float x, float y, float *color, int layer_index);

// Same as fond_render, but taking an UTF32
// encoded string of codepoints and its size.
DT_DLL_VRVGRAPHICSUTILS int fond_render_utf(fond_buffer *buffer, int32_t *text, size_t num_chars, float x, float y, float *color, int layer_index);

// Decode the given UTF8 string into an UTF32
// string. The resulting string is put into
// decoded, and its size is put into size.
// This is used by the non _u functions to
// decode the string. You may want to use this
// internally, if you need to re-use the same
// string often and don't wnat to pay the
// conversion cost.
DT_DLL_VRVGRAPHICSUTILS int fond_decode_utf8(void *string, int32_t **decoded, size_t *size, FondError & error);


// Return a string for a human-readable error
// message of the given error code.
DT_DLL_VRVGRAPHICSUTILS const char *fond_error_string(FondError error);

// internal functions
//void fond_err(fond_font* font, FondError code);
int fond_check_glerror();
int fond_check_shader(GLuint shader);
int fond_check_program(GLuint program);

struct FondDataWrapper
{
   fond_font m_font;
   fond_buffer m_buffer;
};

typedef std::map<std::string, FondDataWrapper*> FontDataMap;
DT_DLL_VRVGRAPHICSUTILS extern FontDataMap the_font_data;