Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-fond Reference Manual, version 1.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 09:36:25 2021 GMT+0.
| • Introduction | What cl-fond is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
This is a bindings library to libfond, a simple OpenGL text rendering engine.
Precompiled versions of the underlying library are included in this. If you want to build it manually however, refer to the libfond repository.
Load the system through ASDF or Quicklisp:
(ql:quickload :cl-fond)
Before you can create any of the objects, you need to have an OpenGL 3.3+ context current. Creating a context is outside of the scope of this library. Please refer to your framework. Once you do have a context handy, you can create a font object:
(defvar *font* (cl-fond:make-font #p"~/test.ttf" "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ .!?"))
The string there specifies the character set for which the font should be loaded. You will only be able to render characters from that set. Note that the more characters you have and the bigger you make the font size, the larger the texture it will have to allocate to map out the characters. If there is an error of some kind, like being unable to read the file or fit it into a texture atlas, a condition is signalled. Otherwise the font should be readily loaded and you can start working with it.
(compute-extent *font* "Hello there!")
If you actually want to render text, you are given two options:
The former has the advantage of being much simpler, at the cost of rendering to an offscreen texture instead of directly to the screen. The latter gives you more control over how you place and render the text at the cost of having to write your own shaders to do it. Let's look at the easy way first:
(defvar *buffer* (cl-fond:make-buffer *font* 512 30))
With a default font size of 20px, 30px for the height should be enough room. This function may again error if it fails to properly allocate the resources it needs in the back. Once it is ready you can start rendering text to it.
(cl-fond:render *buffer* "Sup man." :y (height *font*))
We set the y coordinate to the height of the font here, as libfond sets 0,0 in the top left corner and x,y of the text on the left of its baseline. Thus in order to make the text visible on the buffer, we need to offset the y coordinate by at least the font's height. Once rendered, it returns the OpenGL texture that it rendered to. You can then render this texture onto a quad in your primary render code. Keep in mind that you need to respect the aspect ratio of the buffer, and that scaling its texture beyond the specified size will make things look blurry.
If you want to manually render the characters instead, you'll want to use compute-text as follows:
(cl-fond:compute-text *font* "Heyo.")
Returned by it will be an OpenGL vertex array to draw with and the number of elements it contains. After binding your shader program and setting things up properly, you can then draw the characters as follows:
(gl:bind-texture :texture-2d (cl-fond:texture *font*))
(gl:bind-vertex-array vao)
(%gl:draw-elements :triangles count :unsigned-int 0)
The VAO contains two vec2 inputs: the position and the texture coordinate. Note that the position is scaled to pixel size. You will likely want to adapt this in your vertex shader to fit appropriately. In your fragment shader you will only want to read out the r component of the texture. Every other component is 0.
See the default vertex and fragment shaders used by the buffer for an example.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The cl-fond system |
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(:git "https://github.com/shirakumo/cl-fond.git")
zlib
Bindings to libfond, a simple text rendering engine for OpenGL
1.1.0
cl-fond.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The cl-fond.asd file | ||
| • The cl-fond/package.lisp file | ||
| • The cl-fond/low-level.lisp file | ||
| • The cl-fond/wrapper.lisp file | ||
| • The cl-fond/documentation.lisp file |
Next: The cl-fond/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-fond.asd
cl-fond (system)
Next: The cl-fond/low-level․lisp file, Previous: The cl-fond․asd file, Up: Lisp files [Contents][Index]
cl-fond (system)
package.lisp
Next: The cl-fond/wrapper․lisp file, Previous: The cl-fond/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
cl-fond (system)
low-level.lisp
*here* (special variable)
Next: The cl-fond/documentation․lisp file, Previous: The cl-fond/low-level․lisp file, Up: Lisp files [Contents][Index]
low-level.lisp (file)
cl-fond (system)
wrapper.lisp
Previous: The cl-fond/wrapper․lisp file, Up: Lisp files [Contents][Index]
wrapper.lisp (file)
cl-fond (system)
documentation.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The cl-fond-cffi package | ||
| • The cl-fond package |
Next: The cl-fond package, Previous: Packages, Up: Packages [Contents][Index]
package.lisp (file)
org.shirakumo.fraf.fond.cffi
*here* (special variable)
Previous: The cl-fond-cffi package, Up: Packages [Contents][Index]
package.lisp (file)
org.shirakumo.fraf.fond
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported conditions | ||
| • Exported classes |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Variable containing the path to the static directory. That directory contains the precompiled library binaries.
low-level.lisp (file)
Next: Exported generic functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Pointer to the font that it renders.
This can be exchanged for another font, if you should
decide to want to render with a different font.
See BUFFER
low-level.lisp (file)
(setf buffer-font) (function)
low-level.lisp (file)
buffer-font (function)
This is an internal field.
See BUFFER
low-level.lisp (file)
(setf buffer-framebuffer) (function)
low-level.lisp (file)
buffer-framebuffer (function)
The height of the texture.
See BUFFER
low-level.lisp (file)
(setf buffer-height) (function)
low-level.lisp (file)
buffer-height (function)
This is an internal field.
See BUFFER
low-level.lisp (file)
(setf buffer-program) (function)
low-level.lisp (file)
buffer-program (function)
The OpenGL texture ID to which this buffer renders to.
See BUFFER
low-level.lisp (file)
(setf buffer-texture) (function)
low-level.lisp (file)
buffer-texture (function)
The width of the texture.
See BUFFER
low-level.lisp (file)
(setf buffer-width) (function)
low-level.lisp (file)
buffer-width (function)
Returns a string containing all the characters this font instance is capable of drawing.
See FONT
wrapper.lisp (file)
Compute the extent of the given text.
You must allocate the extent struct yourself and make
sure it is zeroed out.
See FONT
See EXTENT
low-level.lisp (file)
Compute the extent of the given text in pixels.
Returns a property list with the following entries:
:L — The extent to the left from zero.
:R — The extent to the right from zero.
:T — The extent up from the baseline.
:B — The extent down from the baseline.
:GAP — The gap between two lines of text.
See FONT
wrapper.lisp (file)
Same as COMPUTE-EXTENT but taking an UTF32 encoded string and its size.
See COMPUTE-EXTENT
See FONT
See EXTENT
low-level.lisp (file)
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
returned VAO contains two arrays, at location 0 and 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. 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.
See FONT
low-level.lisp (file)
Compute the vertex array object to draw the given text.
Returns two values: the OpenGL VAO ID, and the number of
elements stored in the VAO.
In order to actually use this, you will need to bind the
font’s texture and use a vertex and fragment shader that
draw the VAO as appropriate. The VAO contains two arrays
of vec2s for this purpose: the first being the vertex
coordinates, and the second being the texture coordinates.
The texture only contains a red component, with the other
components being set to zero.
See FONT
wrapper.lisp (file)
Same as COMPUTE-EXTENT but taking an UTF32 encoded string and its size.
See COMPUTE-TEXT
See FONT
low-level.lisp (file)
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.
low-level.lisp (file)
How far down the text extends from its baseline.
See EXTENT
low-level.lisp (file)
(setf extent-b) (function)
low-level.lisp (file)
extent-b (function)
The gap between lines of the text.
See EXTENT
low-level.lisp (file)
(setf extent-gap) (function)
low-level.lisp (file)
extent-gap (function)
How far to the left the text extends from zero.
See EXTENT
low-level.lisp (file)
(setf extent-l) (function)
low-level.lisp (file)
extent-l (function)
How far to the right the text extends from zero.
See EXTENT
low-level.lisp (file)
(setf extent-r) (function)
low-level.lisp (file)
extent-r (function)
How far up the text extends from its baseline.
See EXTENT
low-level.lisp (file)
(setf extent-t) (function)
low-level.lisp (file)
extent-t (function)
Returns the pathname for the TTF file this font contains.
See FONT
wrapper.lisp (file)
Return the current error code.
low-level.lisp (file)
Return a string for a human-readable error message of the given error code.
low-level.lisp (file)
The OpenGL texture ID for the atlas.
See FONT
low-level.lisp (file)
(setf font-atlas) (function)
low-level.lisp (file)
font-atlas (function)
A UTF8 encoded string of characters that this font instance will be able to render.
Must be null-terminated.
See FONT
low-level.lisp (file)
(setf font-characters) (function)
low-level.lisp (file)
font-characters (function)
This is an internal field.
See FONT
low-level.lisp (file)
(setf font-chardata) (function)
low-level.lisp (file)
font-chardata (function)
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.
See FONT
low-level.lisp (file)
(setf font-codepoints) (function)
low-level.lisp (file)
font-codepoints (function)
This is an internal field.
See FONT
low-level.lisp (file)
(setf font-converted-codepoints) (function)
low-level.lisp (file)
font-converted-codepoints (function)
Accessor for the path to the TTF file.
See FONT
low-level.lisp (file)
(setf font-file) (function)
low-level.lisp (file)
font-file (function)
This is an internal field.
See FONT
low-level.lisp (file)
(setf font-fontdata) (function)
low-level.lisp (file)
font-fontdata (function)
This is an internal field.
See FONT
low-level.lisp (file)
(setf font-fontinfo) (function)
low-level.lisp (file)
font-fontinfo (function)
The height of the glyph texture atlas.
See FONT
low-level.lisp (file)
(setf font-height) (function)
low-level.lisp (file)
font-height (function)
Accessor for the index of the font within the TTF file.
You probably don’t need to set this.
See FONT
low-level.lisp (file)
(setf font-index) (function)
low-level.lisp (file)
font-index (function)
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
See FONT
low-level.lisp (file)
(setf font-oversample) (function)
low-level.lisp (file)
font-oversample (function)
The vertical font size in pixels.
If you render it above this resolution, you’ll get blurring.
See FONT
low-level.lisp (file)
(setf font-size) (function)
low-level.lisp (file)
font-size (function)
The width of the glyph texture atlas.
See FONT
low-level.lisp (file)
(setf font-width) (function)
low-level.lisp (file)
font-width (function)
Free all the data that was allocated into the struct by fond_load_buffer.
This will /not/ free the font struct.
See BUFFER
low-level.lisp (file)
Free all the data that was allocated into the struct by LOAD-FONT*
This will /not/ free the characters array, the file
array, or the codepoints array if the codepoints
array was not computed by LOAD-FONT*
See FONT
low-level.lisp (file)
Load the buffer struct and allocate the necessary OpenGL data.
The following fields must be set in the struct:
font
width
height
See BUFFER
low-level.lisp (file)
Load the font struct and allocate the necessary OpenGL data.
The following fields must be set in the struct:
file
size
width
height
characters or codepoints
See FONT
low-level.lisp (file)
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
See FONT
low-level.lisp (file)
Create a new buffer instance.
The font is the font instance to render with, and the width
and height specify the dimensions of the texture that this
buffer renders to.
See BUFFER
See FONT
wrapper.lisp (file)
Create a new font instance for the given TTF file and character set.
The charset should be a string containing all characters that
the font should be able to draw. The index is the index of the
font within the file. Some TTF files can contain multiple fonts
in one. Usually, you won’t need to set this parameter. Oversample
is the oversampling factor that should be used. Using
oversampling might result in better quality rendering, at the
cost of massively increasing the necessary size of the atlas.
The necessary size is multiplied by the oversampling factor in
both dimensions. The width and height are optional factors that
when given specify the starting texture atlas size to use to
attempt to fit the glyphs. If this size is too small, an error
is signalled.
See FONT
wrapper.lisp (file)
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.
See BUFFER
low-level.lisp (file)
Same as RENDER-BUFFER but taking an UTF32 encoded string and its size.
See RENDER-BUFFER
See BUFFER
low-level.lisp (file)
Returns the font’s size in pixels.
See FONT
wrapper.lisp (file)
Returns the height of a text line from its baseline.
See FONT
wrapper.lisp (file)
low-level.lisp (file)
wrapper.lisp (file)
low-level.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
The error code that the condition carries.
See FOND-ERROR
See CL-FOND-CFFI:FOND-ERROR-STRING
(setf error-code) (generic function)
wrapper.lisp (file)
error-code (generic function)
wrapper.lisp (file)
Accessor to the font that this buffer uses to render with.
You can change this at any time to switch what to render with.
(setf font) (generic function)
automatically generated reader method
wrapper.lisp (file)
font (generic function)
automatically generated writer method
wrapper.lisp (file)
wrapper.lisp (file)
Immediately frees the foreign object associated with the instance.
wrapper.lisp (file)
Accessor to the pointer to the foreign object.
See C-OBJECT
(setf handle) (generic function)
automatically generated reader method
wrapper.lisp (file)
handle (generic function)
automatically generated writer method
wrapper.lisp (file)
Returns the height of the object’s texture.
See TEXTURE
See FONT
See BUFFER
wrapper.lisp (file)
wrapper.lisp (file)
Render the given text to the buffer.
The X and Y coordinates are offsets inside the texture,
counting from the top left, as is usual for graphical
applications. Thus Y grows downwards, rather than upwards
like in OpenGL. The color should be a list of floats in
the range of [0,1] representing RGBA in that order,
defaulting to 1 for each component.
Returns the OpenGL texture ID that we rendered to.
wrapper.lisp (file)
Returns the OpenGL texture ID for the texture contained in the object.
See WIDTH
See HEIGHT
See FONT
See BUFFER
wrapper.lisp (file)
wrapper.lisp (file)
Returns the width of the object’s texture.
See TEXTURE
See FONT
See BUFFER
wrapper.lisp (file)
wrapper.lisp (file)
Next: Exported classes, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Condition signalled when an error occurs in the underlying libfond.
See ERROR-CODE
wrapper.lisp (file)
error (condition)
:error-code
(quote :unknown)
error-code (generic function)
(setf error-code) (generic function)
Previous: Exported conditions, Up: Exported definitions [Contents][Index]
This struct allows for convenience in rendering, as it will render text for you into a texture.
You must allocate this struct yourself and make sure that
it is zeroed out before you do anything with it. Not
zeroing out will land you in a world of pain.
See BUFFER-FONT
See BUFFER-TEXTURE
See BUFFER-WIDTH
See BUFFER-HEIGHT
See BUFFER-PROGRAM
See BUFFER-FRAMEBUFFER
See FREE-BUFFER
See LOAD-BUFFER
See RENDER-BUFFER
See RENDER-BUFFER-U
low-level.lisp (file)
This is a representation of a text buffer.
The buffer allows you to conveniently draw text to a texture.
You will then merely need to draw the texture to the screen,
rather than needing to manually create a shader and handle the
drawing yourself.
See C-OBJECT
See FONT
See MAKE-BUFFER
See RENDER
See WIDTH
See HEIGHT
See TEXTURE
wrapper.lisp (file)
c-object (class)
:font
font (generic function)
(setf font) (generic function)
Base class for all objects that are tied to a foreign object somehow.
See HANDLE
See ALLOCATE-HANDLE
See FREE-HANDLE
See FREE
wrapper.lisp (file)
standard-object (class)
:handle
handle (generic function)
(setf handle) (generic function)
This struct contains information about the extents of a text.
You must allocate this struct yourself and make sure that
it is zeroed out before you do anything with it. Not
zeroing out will land you in a world of pain.
See EXTENT-L
See EXTENT-R
See EXTENT-T
See EXTENT-B
See EXTENT-GAP
See COMPUTE-EXTENT
See COMPUTE-EXTENT-U
low-level.lisp (file)
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. Not
zeroing out will land you in a world of pain.
See FONT-FILE
See FONT-INDEX
See FONT-SIZE
See FONT-CHARACTERS
See FONT-CODEPOINTS
See FONT-WIDTH
See FONT-HEIGHT
See FONT-OVERSAMPLE
See FONT-ATLAS
See FONT-FONTDATA
See FONT-CHARDATA
See FONT-FONTINFO
See FONT-CONVERTED-CODEPOINTS
See LOAD-FONT
See LOAD-FONT-FIT
See FREE-FONT
See COMPUTE-TEXT
See COMPUTE-TEXT-U
See COMPUTE-EXTENT
See COMPUTE-EXTENT-U
low-level.lisp (file)
This is a representation of a font file.
Using this class you can draw and compute text for a specific font at a specific size. The library will take care of rendering the font glyphs to an atlas to allow fast rendering of text.
See C-OBJECT
See MAKE-FONT
See COMPUTE-TEXT
See COMPUTE-EXTENT
See FILE
See SIZE
See TEXT-HEIGHT
See WIDTH
See HEIGHT
See TEXTURE
See CHARSET
wrapper.lisp (file)
c-object (class)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal functions | ||
| • Internal generic functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Variable containing the path to the low-level.lisp file.
low-level.lisp (file)
Next: Internal generic functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Allocate memory for the given foreign type and zero it out.
wrapper.lisp (file)
Check whether any errors occurred in the underlying library and signal an error if necessary.
See FOND-ERROR
See CL-FOND-CFFI:FOND-ERROR
wrapper.lisp (file)
Convert the given string to an UTF8 encoded C-string.
Returns a pointer to the allocated data. You are responsible for freeing it when appropriate.
wrapper.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
Allocate and return a pointer to the foreign object for this class.
See C-OBJECT
wrapper.lisp (file)
Return a function that, when called, frees the given foreign object for this class.
See C-OBJECT
wrapper.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L |
|---|
| Jump to: | C F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | (
A B C D E F G H L M R S T U W |
|---|
| Jump to: | (
A B C D E F G H L M R S T U W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
E F H S |
|---|
| Jump to: | *
E F H S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | B C E F P S |
|---|
| Jump to: | B C E F P S |
|---|