Changeset 33031 in project


Ignore:
Timestamp:
12/25/15 23:29:57 (4 years ago)
Author:
John Croisant
Message:

sdl2: Updated docs.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sdl2-ttf

    r33025 r33031  
    33The sdl2-ttf egg provides bindings to
    44[[http://www.libsdl.org/projects/SDL_ttf/|SDL_ttf]] version 2.
    5 SDL_ttf is a library for rendering TTF and FON fonts,
     5SDL_ttf is a library for rendering TTF, OTF, and FON fonts,
    66compatible with [[http://libsdl.org/|Simple DirectMedia Layer]] version 2 (SDL2),
    77a popular library used in games and other media-rich software.
     
    164164{{ptsize}} is the point size (based on 72DPI) to load the font as. This basically translates to pixel height.
    165165
    166 {{index}} allows you to choose a font face from a file containing multiple font faces. The first face is always index 0.
     166{{index}} allows you to choose a font face from a file containing multiple font faces. It defaults to 0, the first face.
    167167
    168168Returns a ttf:font with the font data.
     
    186186{{ptsize}} is the point size (based on 72DPI) to load the font as. This basically translates to pixel height.
    187187
    188 {{index}} allows you to choose a font face from a file containing multiple font faces. The first face is always index 0.
     188{{index}} allows you to choose a font face from a file containing multiple font faces. It defaults to 0, the first face.
    189189
    190190Returns a ttf:font with the font data.
     
    207207
    208208<procedure>(close-font! font)</procedure>
    209 <procedure>(free-font! font)</procedure>
    210209
    211210See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_18.html#SEC18|TTF_CloseFont]].
     
    216215It is safe (but has no effect) to free a struct record multiple times.
    217216
    218 {{free-font!}} is another name for {[close-font!}}, to be consistent with other free-procedures.
    219 
    220217
    221218==== Font Attributes
     
    239236representing bitwise-or'd integer constants.
    240237
     238'''NOTE:''' Bold and italic styles perform automatic adjustment of the font.
     239The results sometimes do not look very good.
     240For better-looking results, you should instead load the bold or italic versions of your font as a separate ttf:font.
     241
    241242
    242243<procedure>(font-outline font) → integer</procedure>
     
    316317
    317318
     319==== Glyph Metrics
     320
     321<procedure>(glyph-provided font glyph) → integer or #f</procedure>
     322
     323If the glyph is provided by the font, this procedure returns a positive integer,
     324indicating the glyph's index position in the font.
     325If the glyph is not provided by the font, this procedure returns #f.
     326See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_37.html#SEC37|TTF_GlyphIsProvided]].
     327
     328{{glyph}} may be an integer (representing a 16-bit Unicode character) or a Scheme character in the ASCII range.
     329Results may be incorrect if given a Scheme character outside the ASCII range.
     330
     331
     332<procedure>(glyph-metrics font glyph) → [min-x max-x min-y max-y advance]</procedure>
     333
     334Return various metrics about the given glyph.
     335This procedure returns multiple values:
     336
     337; min-x   : the glyph's minimum X offset
     338; max-x   : the glyph's maximum X offset
     339; min-y   : the glyph's minimum Y offset
     340; max-y   : the glyph's maximum Y offset
     341; advance : the glyph's advance offset
     342
     343See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_38.html#SEC38|TTF_GlyphMetrics]].
     344There is a diagram which shows what these metrics mean.
     345
     346{{glyph}} may be an integer (representing a 16-bit Unicode character) or a Scheme character in the ASCII range.
     347Results may be incorrect if given a Scheme character outside the ASCII range.
     348
     349Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     350
     351
    318352
    319353=== Rendering
    320354
    321 ==== Rendering Latin 1 (ISO 8859-1) Text
     355==== Rendering Latin-1 (ISO 8859-1) Text
    322356
    323357<procedure>(size-text font text) → [w h]</procedure>
    324358
    325 Calculate the resulting surface size of the Latin 1 (ISO 8859-1) text rendered using the ttf:font.
     359Calculate the size of the surface that ''would be created'' if you rendered the given Latin-1 (ISO 8859-1) text using the ttf:font.
     360See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_39.html#SEC39|TTF_SizeText]].
     361
    326362Returns two values, the calculated width and the height, as integers.
    327 See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_39.html#SEC39|TTF_SizeText]].
     363
     364This is much faster than actually rendering the text,
     365so you can use this to quickly predict how much space would be needed.
     366This is useful for calculating word wrapping, alignment, truncation, etc.
    328367
    329368
     
    331370<procedure>(render-text-solid* font text fg) → sdl2:surface</procedure>
    332371
    333 Render the given Latin 1 (ISO 8859-1) encoded text using
     372Render the given Latin-1 (ISO 8859-1) encoded text using
    334373[[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_42.html#SEC42|"solid" rendering mode.]]
    335374See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_43.html#SEC43|TTF_RenderText_Solid]].
    336375
    337 * {{font}} is a ttf:font specifying the font to render with.
    338 * {{text}} is a Latin 1 (ISO 8859-1) encoded string specifying the text to render.
    339 * {{fg}} is a sdl2:color specifying the foreground color, i.e. the color of the text itself.
     376* {{font}} must be a ttf:font specifying the font to render with.
     377* {{text}} must be a Latin-1 (ISO 8859-1) encoded string specifying the text to render.
     378* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the text itself.
    340379
    341380Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered text.
     
    349388<procedure>(render-text-shaded* font text fg bg) → sdl2:surface</procedure>
    350389
    351 Render the given Latin 1-encoded text using
     390Render the given Latin-1-encoded text using
    352391[[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_42.html#SEC42|"shaded" rendering mode.]]
    353392See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_43.html#SEC43|TTF_RenderText_Shaded]].
    354393
    355 * {{font}} is a ttf:font specifying the font to render with.
    356 * {{text}} is a Latin 1 (ISO 8859-1) encoded string specifying the text to render.
    357 * {{fg}} is a sdl2:color specifying the foreground color, i.e. the color of the text itself.
    358 * {{bg}} is a sdl2:color specifying the background color.
     394* {{font}} must be a ttf:font specifying the font to render with.
     395* {{text}} must be a Latin-1 (ISO 8859-1) encoded string specifying the text to render.
     396* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the text itself.
     397* {{bg}} must be a sdl2:color specifying the background color.
    359398
    360399Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered text.
     
    368407<procedure>(render-text-blended* font text fg) → sdl2:surface</procedure>
    369408
    370 Render the given Latin 1 (ISO 8859-1) encoded text using
     409Render the given Latin-1 (ISO 8859-1) encoded text using
    371410[[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_42.html#SEC42|"blended" rendering mode.]]
    372411See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_43.html#SEC43|TTF_RenderText_Blended]].
    373412
    374 * {{font}} is a ttf:font specifying the font to render with.
    375 * {{text}} is a Latin 1 (ISO 8859-1) encoded string specifying the text to render.
    376 * {{fg}} is a sdl2:color specifying the foreground color, i.e. the color of the text itself.
     413* {{font}} must be a ttf:font specifying the font to render with.
     414* {{text}} must be a Latin-1 (ISO 8859-1) encoded string specifying the text to render.
     415* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the text itself.
    377416
    378417Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered text.
     
    383422
    384423
     424
    385425==== Rendering UTF8 Text
    386426
    387427<procedure>(size-utf8 font text) → [w h]</procedure>
    388428
    389 Calculate the resulting surface size of the UTF8 text rendered using the given ttf:font.
     429Calculate the size of the surface that ''would be created'' if you rendered the given UTF8 text using the ttf:font.
     430See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_40.html#SEC40|TTF_SizeUTF8]].
     431
    390432Returns two values, the calculated width and the height, as integers.
    391 See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_40.html#SEC40|TTF_SizeUTF8]].
     433
     434This is much faster than actually rendering the text,
     435so you can use this to quickly predict how much space would be needed.
     436This is useful for calculating word wrapping, alignment, truncation, etc.
    392437
    393438
     
    399444See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_43.html#SEC43|TTF_RenderUTF8_Solid]].
    400445
    401 * {{font}} is a ttf:font specifying the font to render with.
    402 * {{text}} is a UTF8 encoded string specifying the text to render.
    403 * {{fg}} is a sdl2:color specifying the foreground color, i.e. the color of the text itself.
     446* {{font}} must be a ttf:font specifying the font to render with.
     447* {{text}} must be a UTF8 encoded string specifying the text to render.
     448* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the text itself.
    404449
    405450Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered text.
     
    417462See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_43.html#SEC43|TTF_RenderUTF8_Shaded]].
    418463
    419 * {{font}} is a ttf:font specifying the font to render with.
    420 * {{text}} is a UTF8 encoded string specifying the text to render.
    421 * {{fg}} is a sdl2:color specifying the foreground color, i.e. the color of the text itself.
    422 * {{bg}} is a sdl2:color specifying the background color.
     464* {{font}} must be a ttf:font specifying the font to render with.
     465* {{text}} must be a UTF8 encoded string specifying the text to render.
     466* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the text itself.
     467* {{bg}} must be a sdl2:color specifying the background color.
    423468
    424469Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered text.
     
    436481See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_43.html#SEC43|TTF_RenderUTF8_Blended]].
    437482
    438 * {{font}} is a ttf:font specifying the font to render with.
    439 * {{text}} is a UTF8 encoded string specifying the text to render.
    440 * {{fg}} is a sdl2:color specifying the foreground color, i.e. the color of the text itself.
     483* {{font}} must be a ttf:font specifying the font to render with.
     484* {{text}} must be a UTF8 encoded string specifying the text to render.
     485* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the text itself.
    441486
    442487Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered text.
     
    447492
    448493
     494
     495==== Rendering Unicode Text
     496
     497<procedure>(byte-swapped-unicode-set! swapped?)</procedure>
     498<constant>UNICODE_BOM_NATIVE</constant>
     499<constant>UNICODE_BOM_SWAPPED</constant>
     500
     501{{byte-swapped-unicode-set!}} sets the default byte order of Unicode chars.
     502If {{swapped?}} is #t, this sets the default byte order to swapped.
     503If {{swapped?}} is #f, this sets the default byte order to native.
     504See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_20.html#SEC20|TTF_ByteSwappedUNICODE]].
     505
     506UNICODE_BOM_NATIVE and UNICODE_BOM_SWAPPED are special Unicode characters (unsigned 16-bit integers).
     507When used in a Unicode string, they temporarily (for the remainder of the string)
     508override whether the byte order of Unicode chars is native or swapped.
     509See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_57.html#SEC57|UNICODE_BOM_NATIVE and UNICODE_BOM_SWAPPED]].
     510
     511
     512<procedure>(size-unicode font unicode) → [w h]</procedure>
     513
     514Calculate the size of the surface that ''would be created'' if you rendered the given 16-bit Unicode encoded text using the ttf:font.
     515See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_41.html#SEC41|TTF_SizeUNICODE]].
     516
     517{{unicode}} must be a pointer or locative to a null-terminated C array of 16-bit unsigned integers, representing Unicode text. ([[/manual/Unit srfi-4|SRFI-4]] u16vectors can be wrapped in a locative using [[/manual/Unit lolevel#make-locative|make-locative]].)
     518
     519Returns two values, the calculated width and the height, as integers.
     520
     521This is much faster than actually rendering the text,
     522so you can use this to quickly predict how much space would be needed.
     523This is useful for calculating word wrapping, alignment, truncation, etc.
     524
     525
     526<procedure>(render-unicode-solid  font unicode fg) → sdl2:surface</procedure>
     527<procedure>(render-unicode-solid* font unicode fg) → sdl2:surface</procedure>
     528
     529Render the given 16-bit Unicode encoded text using
     530[[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_42.html#SEC42|"solid" rendering mode.]]
     531See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_45.html#SEC45|TTF_RenderUNICODE_Solid]].
     532
     533* {{font}} must be a ttf:font specifying the font to render with.
     534* {{unicode}} must be a pointer or locative to a null-terminated C array of 16-bit unsigned integers, representing Unicode text. ([[/manual/Unit srfi-4|SRFI-4]] u16vectors can be wrapped in a locative using [[/manual/Unit lolevel#make-locative|make-locative]].)
     535* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the text itself.
     536
     537Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered text.
     538Signals an exception of kind {{(exn sdl2)}} if an error occurred.
     539
     540* {{render-unicode-solid}} returns a managed sdl2:surface.
     541* {{render-unicode-solid*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
     542
     543
     544<procedure>(render-unicode-shaded  font unicode fg bg) → sdl2:surface</procedure>
     545<procedure>(render-unicode-shaded* font unicode fg bg) → sdl2:surface</procedure>
     546
     547Render the given 16-bit Unicode encoded text using
     548[[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_42.html#SEC42|"shaded" rendering mode.]]
     549See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_49.html#SEC49|TTF_RenderUNICODE_Shaded]].
     550
     551* {{font}} must be a ttf:font specifying the font to render with.
     552* {{unicode}} must be a pointer or locative to a null-terminated C array of 16-bit unsigned integers, representing Unicode text. ([[/manual/Unit srfi-4|SRFI-4]] u16vectors can be wrapped in a locative using [[/manual/Unit lolevel#make-locative|make-locative]].)
     553* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the text itself.
     554* {{bg}} must be a sdl2:color specifying the background color.
     555
     556Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered text.
     557Signals an exception of kind {{(exn sdl2)}} if an error occurred.
     558
     559* {{render-unicode-shaded}} returns a managed sdl2:surface.
     560* {{render-unicode-shaded*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
     561
     562
     563<procedure>(render-unicode-blended  font unicode fg) → sdl2:surface</procedure>
     564<procedure>(render-unicode-blended* font unicode fg) → sdl2:surface</procedure>
     565
     566Render the given 16-bit Unicode encoded text using
     567[[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_42.html#SEC42|"blended" rendering mode.]]
     568See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_53.html#SEC53|TTF_RenderUNICODE_Blended]].
     569
     570* {{font}} must be a ttf:font specifying the font to render with.
     571* {{unicode}} must be a pointer or locative to a null-terminated C array of 16-bit unsigned integers, representing Unicode text. ([[/manual/Unit srfi-4|SRFI-4]] u16vectors can be wrapped in a locative using [[/manual/Unit lolevel#make-locative|make-locative]].)
     572* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the text itself.
     573
     574Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered text.
     575Signals an exception of kind {{(exn sdl2)}} if an error occurred.
     576
     577* {{render-unicode-blended}} returns a managed sdl2:surface.
     578* {{render-unicode-blended*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
     579
     580
     581
     582==== Rendering Individual Glyphs
     583
     584<procedure>(render-glyph-solid  font glyph fg) → sdl2:surface</procedure>
     585<procedure>(render-glyph-solid* font glyph fg) → sdl2:surface</procedure>
     586
     587Render the given glyph using
     588[[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_42.html#SEC42|"solid" rendering mode.]]
     589See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_46.html#SEC46|TTF_RenderGlyph_Solid]].
     590
     591* {{font}} must be a ttf:font specifying the font to render with.
     592* {{glyph}} must be an integer (representing a 16-bit Unicode character) or a Scheme character in the ASCII range.
     593  Results may be incorrect if given a Scheme character outside the ASCII range.
     594* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the glyph itself.
     595
     596Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered glyph.
     597Signals an exception of kind {{(exn sdl2)}} if an error occurred.
     598
     599* {{render-glyph-solid}} returns a managed sdl2:surface.
     600* {{render-glyph-solid*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
     601
     602
     603<procedure>(render-glyph-shaded  font glyph fg bg) → sdl2:surface</procedure>
     604<procedure>(render-glyph-shaded* font glyph fg bg) → sdl2:surface</procedure>
     605
     606Render the given glyph using
     607[[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_42.html#SEC42|"shaded" rendering mode.]]
     608See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_50.html#SEC50|TTF_RenderGlyph_Shaded]].
     609
     610* {{font}} must be a ttf:font specifying the font to render with.
     611* {{glyph}} must be an integer (representing a 16-bit Unicode character) or a Scheme character in the ASCII range.
     612  Results may be incorrect if given a Scheme character outside the ASCII range.
     613* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the glyph itself.
     614* {{bg}} must be a sdl2:color specifying the background color.
     615
     616Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered glyph.
     617Signals an exception of kind {{(exn sdl2)}} if an error occurred.
     618
     619* {{render-glyph-shaded}} returns a managed sdl2:surface.
     620* {{render-glyph-shaded*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
     621
     622
     623<procedure>(render-glyph-blended  font glyph fg) → sdl2:surface</procedure>
     624<procedure>(render-glyph-blended* font glyph fg) → sdl2:surface</procedure>
     625
     626Render the given glyph using
     627[[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_42.html#SEC42|"blended" rendering mode.]]
     628See [[http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf_54.html#SEC54|TTF_RenderGlyph_Blended]].
     629
     630* {{font}} must be a ttf:font specifying the font to render with.
     631* {{glyph}} must be an integer (representing a 16-bit Unicode character) or a Scheme character in the ASCII range.
     632  Results may be incorrect if given a Scheme character outside the ASCII range.
     633* {{fg}} must be a sdl2:color specifying the foreground color, i.e. the color of the glyph itself.
     634
     635Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the rendered glyph.
     636Signals an exception of kind {{(exn sdl2)}} if an error occurred.
     637
     638* {{render-glyph-blended}} returns a managed sdl2:surface.
     639* {{render-glyph-blended*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
Note: See TracChangeset for help on using the changeset viewer.