intraFont - A bitmap font library for PSP using the PSP's internal font (firmware pgf files)

intraFont Version 0.25 by BenHur - http://www.psp-programming.com/benhur

intraFont uses parts of pgeFont by InsertWittyName - http://insomniac.0x89.org

-=Info=-

The library loads a pgf font from firmware and generates a 4-bit paletted bitmap font texture on
the fly when drawing text. It caches previously drawn characters and is accurate to 1/4 pixel.

As of version 0.22 intraFont supports regular, italic and/or bold Latin, Japanese, Korean and
symbol fonts: flash0:/font/ltn0.pgf, ltn1.pgf, ..., ltn15.pgf, jpn0.pgf, kr0.pgf and arib.pgf
(kr0.pgf and arib.pgf might be missing/replaced by a dummy file depending on the CFW).

Known issues:
- if more than 100 different characters are drawn on the same screen (i.e. before the next
  sceGuSync statement) using a medium size cache (default), graphical glitches might appear.
  Workaround: use a larger cache size (INTRAFONT_CACHE_LARGE or INTRAFONT_CACHE_ALL)

-=Samples=-

There are two samples included, one for raw GU and the other using the graphics library from
Yeldarb's tutorials on psp-programming.com

If you're using the graphics library then you may need to reset the sceGuTex* states to what
they are defaulted to in the initGraphics() functions, after using the intraFont* functions.

It should be easy enough to add to any other library.

-=Dependencies=-

none (i.e. freetype is NOT required)

-=Performance=-

Depending on the purpose one can optimize the use of intraFont for loadtime [ms], memory [kB] and 
speed [kiloCharacters Per Second] via the INTRAFONT_CACHE_??? flags.

Rule of thumb: 
- if you only need standard ASCII characters in your application: 
    use INTRAFONT_CACHE_ASCII
- if you need less than 100 different characters in your application: 
    use INTRAFONT_CACHE_MED (default)
- if you use more than 100 different characters in your application: 
    use INTRAFONT_CACHE_LARGE for faster loadtime  OR
    use INTRAFONT_CACHE_ALL for lower memory consumption and steady fps       

The following table shows typical performance numbers:

font:    INTRAFONT_CACHE_MED (def)   INTRAFONT_CACHE_LARGE   INTRAFONT_CACHE_ASCII   INTRAFONT_CACHE_ALL
--------+---------------------------+-------------------------+-----------------------+--------------------------
ltn0-7     52ms,  114kB, 2.5kCPS(*)   52ms,  210kB, 2.5kCPS   83ms, 33kB, 100kCPS    191ms, 119kB, 100kCPS
ltn8-15    36ms,   83kB, 4.1kCPS      36ms,  179kB, 4.1kCPS   54ms, 20kB, 100kCPS     95ms,  64kB, 100kCPS
jpn0     1020ms, 1763kB, 0.5kCPS    1020ms, 1859kB, 0.5kCPS  997ms, 33kB, 100kCPS     - too many glyphs -
kr0       350ms,  625kB, 0.6kCPS     350ms,  721kB, 0.6kCPS   - no ASCII glyphs -   1936ms, 440kB, 67kCPS(**)
arib      177ms,  266kB, 1.9kCPS     177ms,  362kB, 1.9kCPS   - no ASCII glyphs -     - too many glyphs -
--------------------------------------------------------------------------------------+--------------------------

(*)  Low speeds (<10kCPS) occur when characters are not cached. Printing the same characters a
     second time results in 100 kCPS, i.e. the speed penalty is gone.
(**) kr0 is slower because one character can consist of up to three glyphs.

If you don't need the S-JIS string parsing: add -DINTRAFONT_NO_SJIS to the CFLAGS in your makefile
(this excludes the conversion table and saves around 18kB).
If you don't need the codepage conversion: add -DINTRAFONT_NO_CP to the CFLAGS in your makefile
(this excludes the conversion table and saves around 1.5kB).

-=Changelog=-

0.25 - added text scrolling in intraFontPrintColumn() (flags INTRAFONT_SCROLL_LEFT/RIGHT/SEESAW/THROUGH)

0.24 - added column printing with automatic linebreaks - no need to worry about overwriting  
       parts of the screen or printing outside the screen anymore (use intraFontPrintColumn()) 
     - added full justification (flush left&right) for column printing (flag INTRAFONT_ALIGN_FULL)
     - various optimizations related to UCS2 conversion (thanks to StrmnNrmn)
     - added functions to print/measure the first n chars of a string (intraFontPrintEx() and
       other ...Ex() functions; thanks to StrmnNrmn)
     - bug fixed where intraFontMeasureText() could return a wrong value because multi-byte 
       strings (S-JIS and UTF-8) and codepages were not yet properly handled

0.23 - added support for UTF-8 string parsing: use flag INTRAFONT_STRING_UTF8 in intraFontLoad()
       (thanks to NexTOS)
     - added support for codepages (conversion of extended ascii to unicode depending on source):
       use flag INTRAFONT_STRING_CP??? in intraFontLoad(), where ??? is 437, 850 or 1252
       (let me know if you need other codepages; default conversion uses ISO-8859-1)
     - encoding type of text string (ASCII, UTF-8, S-JIS or codepage x) can also be set with
       intraFontSetEncoding()

0.22 - added support for S-JIS string parsing: use flag INTRAFONT_STRING_SJIS in intraFontLoad()        
       (thanks to psp-kaihatu-yotien - http://psp.nukenin.jp/ http://ameblo.jp/pspdevblog/ )
     - added pre-caching for ASCII characters: use flag INTRAFONT_CACHE_ASCII in intraFontLoad()
     - added support for extended ASCII in text strings (e.g. "\251" for the (c) copyright symbol)

0.21 - no new features, bugfix version only
     - bug fixed which could cause graphical glitches (thanks to StrmnNrmn)
     - bug fixed where intraFontMeasureText() could return a wrong value (thanks to StrmnNrmn)

0.2  - added support for Korean (kr0.pgf) and symbols (arib.pgf)
     - added cache options (cache size and pre-cache all)
     - added right and center alignments
     - improved fixed width appearance (width can be set by user or left as default)
     - fixed various bugs (mostly in glyph cache to prevent graphical glitches)
     - reduced memory required (variable-size texture, free unneeded stuff)
     - improved speed (optimizations, texture swizzling)

0.1  - initial release

-=Credits=-

Skylark and Freeplay: basic deciphering of the pgf format
InsertWittyName: pgeFont
CpuWhiz: "Hello World" in Japanese
J.F.: intraFontMeasureText()
psp-kaihatu-yotien: S-JIS to UCS-2 conversion
NexTOS: UTF-8 support
StrmnNrmn: bug fixes and optimizations


-=License=-

This is released under the Creative Commons Attribution-Share Alike 3.0 License.
See LICENSE for more information.

-=Atttribution=-

With accordance to the license, the following must be adhered to:

If you use the code in any way, shape or form you must attribute it in the following way:

'Uses intraFont by BenHur'

If you alter the code in any way, shape or form you must also release the updated code
under the same license.

See http://creativecommons.org/licenses/by-sa/3.0/ if you need more information.
 