LISPBUILDER-SDL-TTF -

 

Abstract

LISPBUILDER-SDL-TTF provides a Lisp wrapper for the SDL_TTF library, and provides support for loading and rendering True-Type fonts in an SDL application. The SDL_TTF wrapper is in itself a wrapper around the FreeType 1.2 library, available at: Freetype Homepage. LISPBUILDER-SDL-TTF has a dependency on the LISPBUILDER-SDL package. LISPBUILDER-SDL-TTF is distributed under the MIT-style license.

Current Version: The current version of LISPBUILDER-SDL-TTF is version 0.2.

Package Overview

The TrueType library is automatically initialized and uninitialized by the LISPBUILDER-SDL package. The functions INIT-TTF and QUIT-TTF are added to the lists SDL:*EXTERNAL-INIT-ON-STARTUP* and SDL:*EXTERNAL-QUIT-ON-EXIT*. LISPBUILDER-SDL iterates over these lists in calls to SDL:INIT-SDL, SDL:QUIT-SDL and SDL:WITH-INIT in order to initialize or uninitialize any external libraries such as LISPBUILDER-SDL-TTF.

To open a TrueType font use INITIALISE-FONT or the macro WITH-OPEN-FONT. LISPBUILDER-SDL-TTF allows more than one FONT to be used simultaneously within a single SDL application.

LISPBUILDER-SDL-TTF has the concept of a *DEFAULT-FONT*. A FONT may be bound to *DEFAULT-FONT* by using INITIALISE-DEFAULT-FONT, WITH-OPEN-FONT, or WITH-DEFAULT-FONT. All functions that take a &KEYword or &OPTIONAL FONT argument accept *DEFAULT-FONT* unless a FONT is specified. This makes calling functions a bit easier as the :FONT parameter need not be explicitely passed. For example: (GET-FONT-SIZE "TEXT" :SIZE :W), compared to (GET-FONT-SIZE "TEXT" :SIZE :W :FONT ANY-FONT)

Functions and symbols exported from the LISPBUILDER-SDL-TTF package are accessible from the LISPBUILDER-SDL-TTF: prefix or the shorter form SDL-TTF: nickname.

Simple Example

  (sdl:with-init ()
    (sdl:window 320 240)
    (sdl-ttf:initialise-default-font)
    (sdl-ttf:draw-string-solid-* "Hello TTF World!" 25 50
			   :color (sdl:color :r 255 :g 0 :b 255))
    (sdl:with-events ()
      (:quit-event () t)
      (:video-expose-event () (sdl:update-display))))
      

The LISPBUILDER-SDL-TTF dictionary Index

1. *default-font*
2. *default-font-path*
3. close-font
4. draw-font
5. draw-font
6. draw-font-at
7. draw-font-at-*
8. draw-string-blended
9. draw-string-blended-*
10. draw-string-shaded
11. draw-string-shaded-*
12. draw-string-solid
13. draw-string-solid-*
14. font
15. free-font
16. get-font-ascent
17. get-font-descent
18. get-font-face-family-name
19. get-font-face-style-name
20. get-font-faces
21. get-font-height
22. get-font-line-skip
23. get-font-size
24. get-font-style
25. get-glyph-metric
26. init-ttf
27. initialise-default-font
28. initialise-font
29. is-font-face-fixed-width
30. is-init
31. new-font
32. open-font
33. quit-ttf
34. render-string-blended
35. render-string-shaded
36. render-string-solid
37. set-font-style
38. with-default-font
39. with-open-font

Compatibility

Download

• Development: Available via anonymous SVN at:

  	      svn co https://lispbuilder.svn.sourceforge.net/svnroot/lispbuilder lispbuilder
  	    

• Stable: The latest stable versions are available from the LISPBUILDER-SDL repository on SourceForge.
• The Edi Weitz 'Starter Pack' Version: The stable version of Lispbuilder, suitable for the installation of installation LISPBUILDER-SDL-TTF using the Lisp Starter Pack from Edi Weitz is can be downloaded from http://www.balooga.com/lispbuilder/lispbuilder-sdl-ttf.zip.

Installation

See the LISPBUILDER documentation for installation instructions.

Build Instructions

LISPBUILDER-SDL-TTF requires that a glue library lispbuilder-sdl-ttf-glue is also installed in the library search path. lispbuilder-sdl-ttf-glue wraps the native font rendering functions provided by SDL_TTF as these functions require that a SDL_Color struct is passed by value. However CFFI only supports passing structs by reference.

Windows Build Instructions

lispbuilder-sdl-ttf-glue is installed as part of the LISPBUILDER-SDL-TTF-BINARIES package into the directory LISPBUILDER-SDL-TTF/BIN.

To rebuild the glue library:

1. A working installation of MingW is required.
2. Make sure that the path to the include files for SDL and SDL_TTF are specified correctly in LISPBUILDER-SDL-TTF/Makefile.mingw. Modify the existing line SDL_TTF_CFLAGS=$(CFLAGS) -ISDL-1.2.11/include -ISDL_ttf-2.0.8.
3. In the LISPBUILDER-SDL-TTF/ directory, execute make to create the glue library.
4. If the build is successful, the lispbuilder-sdl-ttf-glue library will be found in the LISPBUILDER-SDL-TTF/BUILD/ directory.
5. Copy or move this file LISPBUILDER-SDL-TTF/BUILD/lispbuilder-sdl-ttf-glue.dll to the BIN directory LISPBUILDER-SDL-TTF/BIN/lispbuilder-sdl-ttf-glue.dll

Linux Build Instructions

To rebuild the glue library:

1. In the LISPBUILDER-SDL-TTF/ directory, execute make to create the glue library.
2. If the build is successful, the lispbuilder-sdl-ttf-glue library will be found in the LISPBUILDER-SDL-TTF/BUILD/ directory.
3. In the LISPBUILDER-SDL-TTF/ directory, execute make install_ttf to install the lispbuilder-sdl-ttf-glue library.

Using LISPBUILDER-SDL-TTF

See the LISPBUILDER documentation for Usage instructions.

Running Examples in LISPBUILDER-SDL-TTF-EXAMPLES

The following examples are contained in the package LISPBUILDER-SDL-TTF-EXAMPLES:

• (SDL-TTF-EXAMPLES:FONT-EXAMPLE)

Enter the following at the REPL to load the examples in the LISPBUILDER-SDL-TTF-EXAMPLES package:

	  (asdf:operate 'asdf:load-op :lispbuilder-sdl-TTF-examples)
	

Dependencies

LISPBUILDER-SDL-TTF has a dependency on LISPBUILDER-SDL.

License

LISPBUILDER-SDL-TTF is distributed under the MIT-style license.

The LISPBUILDER-SDL-TTF dictionary

[Special variable]
*default-font*

When a LISPBUILDER-SDL-TTF function or macro has an OPTIONAL or KEYword argument FONT, the default action is to bind to *DEFAULT-FONT*. *DEFAULT-FONT* is set to NIL initially. A font must be initialized by calling WITH-OPEN-FONT, INITIALISE-FONT, or INITIALISE-DEFAULT-FONT. These will bind *DEFAULT-FONT* to a Truetype font FONT.

[Special variable]
*default-font-path*

The path to the default Truetype font, "Bitstream Vera"

[Function]
close-font &key font *default-font* => result

Closes the font FONT when the SDL_TTF font library is intitialized. NOTE: CLOSE-FONT does not uninitialise the font library, and does not bind *DEFAULT-FONT* to NIL. Returns T if successful, or NIL if the font cannot be closed or the SDL_TTF font library is not initialized.

[Generic function]
draw-font &key font surface => result

Blit the cached SURFACE in FONT to the destination surface SURFACE. The cached surface is created during a previous call to any of the DRAW-STRING* functions. Uses POSITION in the cached SURFACE to render to the X/Y coordinates on the destination SURFACE.

This function can speed up blitting when the text remains unchanged between screen updates.

[Function]
draw-font &key font surface => result

[Generic function]
draw-font-at position &key font surface => result

See DRAW-FONT. POINT is used to position the cached SURFACE, where POINT is of type SDL:POINT.

[Method]
draw-font-at position &key font surface => result

[Generic function]
draw-font-at-* x y &key font surface => result

See DRAW-FONT. X and Y are used to position the cached SURFACE, where X and Y are INTEGERS.

[Method]
draw-font-at-* x y &key font surface => result

[Function]
draw-string-blended text position &key font surface color => result

See DRAW-STRING-BLENDED-*.

• POSITION is the X and Y coordinates to render TEXT, of type SDL:POINT.

[Function]
draw-string-blended-* text x y &key font surface color => result

Draw text TEXT using font FONT with color COLOR onto surface SURFACE, using the Blended mode.

Parameters

• TEXT is the text to render, of type STRING.
• X and Y are the x and y coordinates of the TEXT, as INTEGERs.
• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.
• SURFACE is the target surface, of type SDL:SDL-SURFACE.
• COLOR is the color used to render TEXT, of type SDL:SDL-COLOR

Return

• Returns the font FONT.

Example

(DRAW-STRING-SOLID-* "Hello World!" 0 0 :FONT *DEFAULT-FONT* :SURFACE A-SURFACE :COLOR A-COLOR)

[Function]
draw-string-shaded text position fg-color bg-color &key font surface => result

See DRAW-STRING-SHADED-*

Parmeters

• POSITION is the X and Y coordinates to render TEXT, of type SDL:POINT.

[Function]
draw-string-shaded-* text x y fg-color bg-color &key font surface => result

Draw text TEXT using font FONT with foreground color FG-COLOR and background color BG-COLOR onto surface SURFACE, using the Shaded mode.

Parameters

• TEXT is the text to render, of type STRING.
• X and Y are the x and y coordinates of the TEXT, as INTEGERs.
• FG-COLOR is the foreground color of the TEXT, of type SDL:SDL-COLOR
• BG-COLOR is the background color of the TEXT, of type SDL:SDL-COLOR
• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.
• SURFACE is the target surface, of type SDL:SDL-SURFACE.

Return

• Returns the font FONT.

Example

(DRAW-STRING-SHADED-* "Hello World!" 0 0 fg-col bg-col :FONT *DEFAULT-FONT* :SURFACE A-SURFACE)

[Function]
draw-string-solid text position &key font surface color => result

See DRAW-STRING-SOLID-*.

Parmeters

• POSITION is the X and Y coordinates to render TEXT, of type SDL:POINT.

[Function]
draw-string-solid-* text x y &key font surface color => result

Draw text TEXT using font FONT with color COLOR onto surface SURFACE, using the Solid mode.

Parameters

• TEXT is the text to render, of type STRING.
• X and Y are the x and y coordinates of the TEXT, as INTEGERs.
• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.
• SURFACE is the target surface, of type SDL:SDL-SURFACE.
• COLOR is the color used to render TEXT, of type SDL:SDL-COLOR

Return

• Returns the font FONT.

Example

(DRAW-STRING-SOLID-* "Hello World!" 0 0 :FONT *DEFAULT-FONT* :SURFACE A-SURFACE :COLOR A-COLOR)

[Standard class]
font

A FONT object is wrapper around a foreign TTF_Font object.

The FONT object maintains the most recent surface SDL:SURFACE created by a call to any of the RENDER-STRING* functions. Use DRAW-FONT, DRAW-FONT-AT or DRAW-FONT-AT-* to draw the cached surface.

Prior to the first call to a RENDER-STRING* function, the cached surface is NIL.

[Generic function]
free-font font => result

[Method]
free-font (font font) => result

Free the resources used by the font FONT. Free's any cached surface. Closes the TTF_Font object only when the FONT was created within the current INIT-TTF/QUIT-TTF sequence. In other words, when (EQ (GENERATION FONT) *GENERATION). Otherwise it is assumed that the TTF_Font was closed in a previous call to QUIT-TTF.

[Function]
get-font-ascent &key font => result

Returns the maximum pixel ascent of all glyphs of font FONT. This can also be interpreted as the distance from the top of the font to the baseline. It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.

Parameters

• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.

Returns

• Returns the ascent of the FONT as an INTEGER.

[Function]
get-font-descent &key font => result

Returns the maximum pixel descent of all glyphs of font FONT. This can also be interpreted as the distance from the baseline to the bottom of the font. It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph’s maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.

Parameters

• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.

Returns

• Returns the descent of the FONT as an INTEGER.

[Function]
get-font-face-family-name &key font => result

Returns the current font face family name of font FONT or NIL if the information is unavailable.

Parameters

• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.

Returns

• Returns the name of the FONT face family name as a STRING, or NIL if unavailable.

[Function]
get-font-face-style-name &key font => result

Returns the current font face style name of font FONT, or NIL if the information is unavailable.

Parameters

• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.

Returns

• Returns the name of the FONT face style as a STRING, or NIL if unavailable.

[Function]
get-font-faces &key font => result

Returns the number of faces 'sub-fonts' available in the font FONT. This is a count of the number of specific fonts (based on size and style and other typographical features perhaps) contained in the font itself. It seems to be a useless fact to know, since it can’t be applied in any other SDL_TTF functions.

Parameters

• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.

Returns

• Returns the number of faces in the FONT as an INTEGER.

[Function]
get-font-height &key font => result

Returns the maximum pixel height of all glyphs of font FONT. Use this height for rendering text as close together vertically as possible, though adding at least one pixel height to it will space it so they can't touch. Remember that SDL_TTF doesn't handle multiline printing so you are responsible for line spacing, see GET-FONT-LINE-SKIP as well.

Parameters

• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.

Returns

• Retuns the height of the FONT as an INTEGER.

[Function]
get-font-line-skip &key font => result

Returns the recommended pixel height of a rendered line of text of the font FONT. This is usually larger than the GET-FONT-HEIGHT of the font.

Parameters

• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.

Returns

• Returns the pixel height of the FONT as an INTEGER.

[Function]
get-font-size text &key size font => result

Calculates and returns the resulting SIZE of the SDL:SURFACE that is required to render the text TEXT, or NIL on error. No actual rendering is performed, however correct kerning is calculated for the actual width. The height returned is the same as returned using GET-FONT-HEIGHT.

Parameters

• TEXT is the string to size, of type STRING.
• SIZE must be one of; :W for the text width or :H for the text height.
• FONT is the font used to calculate the size of the TEXT. Binds to *DEFAULT-FONT* by default.

Return

• Returns the width or height of the specified SDL:SURFACE, or NIL upon error.

[Function]
get-font-style &key font => result

Returns the rendering style of the font FONT. If no style is set then :STYLE-NORMAL is returned, or NIL upon error.

Parameters

• FONT is a FONT object. Binfs to *DEFAULT-FONT* by default.

Return

• Retuns the font style as one or more of: :STYLE-NORMAL, :STYLE-BOLD, :STYLE-ITALIC, :STYLE-UNDERLINE

[Function]
get-glyph-metric ch &key metric font => result

Returns the glyph metrics METRIC for the character CH, or NIL upon error.

Parameters

• CH is a UNICODE chararacter specified as an INTEGER.
• FONT is a FONT object from which to retrieve the glyph metrics of the character CH. Binds to *DEFAULT-FONT* by default.
• METRIC is a KEYword argument and may be one of; :MINX, for the minimum X offset. :MAXX, for the maximum X offset. :MINY, for the minimum Y offset. :MAXY, for the maximum Y offset. :ADVANCE, for the advance offset.

Return

• Returns the glyph metric as an INTEGER.

Example

(GET-GLYPH-METRIC UNICODE-CHAR :METRIC :MINX :FONT *DEFAULT-FONT*)

[Function]
init-ttf => result

Initializes the SDL_TTF font library if uninitialized. Returns T if the library was uninitialized and is successfully initialized, or else returns NIL if uninitialized.

[Function]
initialise-default-font &optional free filename size => result

Creates a new FONT object that is loaded from the file at location FILENAME, and binds this to the symbol *DEFAULT-FONT*. Although several truetype fonts may used within a single SDL application, only a single FONT may be bound to the symbol *DEFAULT-FONT* at any one time. Generates an ERROR if FREE is NIL and *DEFAULT-FONT* is already bound to a FONT when INITIALISE-DEFAULT-FONT is called.

Parameters

• FREE when set to T will automatically free any font that is already bound to *DEFAULT-FONT*.
• FILENAME is the optional file name of the font, as a STRING. Default value is Vera.ttf.
• SIZE is the INTEGER point size of the new FONT.

Return

• Returns a new FONT, or NIL if unsuccessful.

[Function]
initialise-font filename size => result

Creates a new FONT object of size SIZE loaded from the file at location FILENAME. Automatically initialises the SDL_TTF truetype font library if the library is uninitialised when FONT is loaded.

Parameters

• FILENAME is the file name of the FONT, of type STRING.
• SIZE is the INTEGER point size of the new FONT.

Return

• Returns a new FONT, or NIL if unsuccessful.

[Function]
is-font-face-fixed-width &key font => result

Returns T if the font face is of a fixed width, or NIL otherwise. Fixed width fonts are monospace, meaning every character that exists in the font is the same width.

Parameters

• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.

Returns

• Retuns T if FONT is of fixed width, and NIL otherwise.

[Function]
is-init => result

Queries the initialization status of the SDL_TTF truetype library. Returns T if this library is already initialized and NIL if uninitialized.

[Function]
new-font fp => result

Creates and returns a new FONT object when FP is a pointer to a foreign TTF_Font object. Returns NIL otherwise.

[Function]
open-font filename size => result

Creates a new FONT from the file loaded at the location specified by FILENAME. NOTE: Does not bind the new FONT to *DEFAULT-FONT*. Does not attempt to initialize the SDL_TTF truetype library if the library is uninitialised.

Parameters

• FILENAME is the name of the truetype font to be loaded, of type STRING
• SIZE is the size of the FONT, as an INTEGER.

Returns

• Returns new FONT object if successful, returns NIL if unsuccessful.

[Function]
quit-ttf => result

Uninitializes the SDL_TTF font library if already initialized. Increments the *generation* count. Returns NIL.

[Function]
render-string-blended text &key font color free cache => result

Render text TEXT using font FONT with color COLOR into a new SURFACE, using the Blended mode. Unless :FREE T, the caller is responsible for freeing the new SURFACE. Use :CACHE T to cache the newly created surface in the FONT object.

Parameters

• TEXT is the text to render, of type STRING.
• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.
• COLOR is the color used to render the TEXT, of type SDL:SDL-COLOR
• FREE when T will free the existing cached SURFACE in FONT.
• CACHE when T will cache the newly created SURFACE in FONT.

Return

• Returns the new surface SDL:SDL-SURFACE.

Example

(DRAW-STRING-BLENDED "Hello World!" :FONT *DEFAULT-FONT* :COLOR A-COLOR)

[Function]
render-string-shaded text fg-color bg-color &key font free cache => result

Render text TEXT using font FONT with foreground and background colors FG-COLOR and BG-COLOR into a new SURFACE, using the Solid mode. Unless :FREE T, the caller is responsible for freeing the new SURFACE. Use :CACHE T to cache the newly created surface in the FONT object.

Parameters

• TEXT is the text to render, of type STRING.
• FG-COLOR is the foreground color of the TEXT, of type SDL:SDL-COLOR
• BG-COLOR is the background color of the TEXT, of type SDL:SDL-COLOR
• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.
• FREE when T will free the existing cached SURFACE in FONT.
• CACHE when T will cache the newly created SURFACE in FONT.

Return

• Returns the new surface SDL:SDL-SURFACE.

Example

(DRAW-STRING-SHADED "Hello World!" fg-col bg-col :FONT DEFAULT-FONT :COLOR A-COLOR)

[Function]
render-string-solid text &key font color free cache => result

Render text TEXT using font FONT with color COLOR into a new SURFACE, using the Solid mode. Unless :FREE T, the caller is responsible for freeing the new SURFACE. Use :CACHE T to cache the newly created surface in the FONT object.

Parameters

• TEXT is the text to render, of type STRING.
• FONT is a FONT object. Binds to *DEFAULT-FONT* by default.
• COLOR is the color used to render the TEXT, of type SDL:SDL-COLOR
• FREE when T will free the existing cached SURFACE in FONT.
• CACHE when T will cache the newly created SURFACE in FONT.

Return

• Returns the new surface SDL:SDL-SURFACE.

Example

 (DRAW-STRING-SOLID "Hello World!" :FONT *DEFAULT-FONT* :COLOR A-COLOR)

[Function]
set-font-style style &key font => result

Sets the rendering style STYLE of font FONT. This will flush the internal cache of previously rendered glyphs, even if there is no change in style, so it may be best to check the current style using GET-FONT-STYLE first.

Parameters

• FONT is a FONT object.
• STYLE is a list of one or more: :STYLE-NORMAL, :STYLE-BOLD, :STYLE-ITALIC, :STYLE-UNDERLINE. NOTE: Combining :STYLE-UNDERLINE with anything can cause a segfault, other combinations may also do this.

[Macro]
with-default-font (font) declaration* statement* => result

Binds FONT to *DEFAULT-FONT* within the scope of WITH-DEFAULT-FONT.

[Macro]
with-open-font (font-name size) declaration* statement* => result

This is a convenience macro that will first attempt to initialize the truetype font library and if successful, will then open the font in the file FONT-NAME prior to evaluating the forms in BODY. Will exit if the library cannot be initialized or the FONT cannot be opened. Closes FONT after the forms in BODY have evaluated.

Binds FONT to a shadowed instance of *DEFAULT-FONT* valid within the scope of WITH-OPEN-FONT. WITH-OPEN-FONT calls may be nested.

Parameters

• FONT-NAME is the file name of the truetype font to be opened, of type STRING.
• SIZE is the INTEGER point size of the font.

Acknowledgements

• Documentation prepared using:
• Edi Weitz's DOCUMENTATION-TEMPLATE.
• Gary King's CL-MARKDOWN.

BACK