// //------------------ DOK FILE -------------------------------------------------- +Header core.2d.font =pkg core.2d.font =title core.2d.font =short =desc This library lets you draw text in a [[Bitmap]]. Fonts are provided as either: - fixed width fonts: a bitmap where all glyphs have the same size and are organized in a grid. See [[fontFixedFromBitmap]] - variable width fonts: a bitmap containing supplemental information for each glyph about width and horizontal overflow. See [[fontFromBitmap]]. You may create and download such a bitmap with our [FontMaker online tool](https://minimacy.net/book/#/font_maker). Text may be provided as Latin or Utf-8 strings. // // //------------------ PROTO ----------------------------------------------------- bitmapMultiLineTextU8 +Proto bitmapMultiLineTextU8 =type fun Bitmap Int Int Int Int Int Str Font Int Int -> Bitmap =mode Function =pkg core.2d.font =impl mcy =link =desc This function draws a text in a bitmap, inside a specified width. It may break the text in multiple lines in order to respect this width. x is the left coordinate of the drawing area. The text will be displayed inside [x, x+w]. The actual meaning of y coordinate depends on the alignment flag: for example with ALIGN_BOTTOM, y is the bottom coordinate of the text area. The function takes care of clipping. See [[bitmapMultiLineText]] for Latin strings. // +arg bmp =type Bitmap =desc any bitmap // +arg x =type Int =desc horizontal position // +arg y =type Int =desc vertical position // +arg w =type Int =desc width // +arg lineSpacing =type Int =desc space to add between lines // +arg flag =type Int =desc a combination of ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT and ALIGN_TOP, ALIGN_BOTTOM, ALIGN_BASELINE, ALIGN_MIDDLE. Default is ALIGN_LEFT|ALIGN_TOP. // +arg text =type Str =desc An utf-8 string // +arg f =type Font =desc A font // +arg foreground =type Int =desc A foreground color // +arg background =type Int =desc A background color, or [[nil]] if none // +arg result =type Bitmap =desc the same bitmap // // //------------------ PROTO ----------------------------------------------------- bitmapMultiLineText +Proto bitmapMultiLineText =type fun Bitmap Int Int Int Int Int Str Font Int Int -> Bitmap =mode Function =pkg core.2d.font =impl mcy =link =desc This function draws a text in a bitmap, inside a specified width. It may break the text in multiple lines in order to respect this width. x is the left coordinate of the drawing area. The text will be displayed inside [x, x+w]. The actual meaning of y coordinate depends on the alignment flag: for example with ALIGN_BOTTOM, y is the bottom coordinate of the text area. The function takes care of clipping. See [[bitmapMultiLineTextU8]] for Utf-8 strings. // +arg bmp =type Bitmap =desc any bitmap // +arg x =type Int =desc horizontal position // +arg y =type Int =desc vertical position // +arg w =type Int =desc width // +arg lineSpacing =type Int =desc space to add between lines // +arg flag =type Int =desc a combination of ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT and ALIGN_TOP, ALIGN_BOTTOM, ALIGN_BASELINE, ALIGN_MIDDLE. Default is ALIGN_LEFT|ALIGN_TOP. // +arg text =type Str =desc A Latin string // +arg font =type Font =desc A font // +arg foreground =type Int =desc A foreground color // +arg background =type Int =desc A background color, or [[nil]] if none // +arg result =type Bitmap =desc the same bitmap // // //------------------ PROTO ----------------------------------------------------- bitmapTextU8 +Proto bitmapTextU8 =type fun Bitmap Int Int Int Str Font Int Int -> Bitmap =mode Function =pkg core.2d.font =impl mcy =link =desc This function draws a text in a bitmap on a single line. The actual meaning of x and y coordinates depends on the alignment flag: for example with ALIGN_RIGHT, x is the right coordinate of the text area. The function takes care of clipping. See [[bitmapText]] for Latin strings. // +arg bmp =type Bitmap =desc any bitmap // +arg x =type Int =desc horizontal position // +arg y =type Int =desc vertical position // +arg flag =type Int =desc a combination of ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT and ALIGN_TOP, ALIGN_BOTTOM, ALIGN_BASELINE, ALIGN_MIDDLE. Default is ALIGN_LEFT|ALIGN_TOP. // +arg text =type Str =desc An Utf-8 string // +arg font =type Font =desc A font // +arg foreground =type Int =desc A foreground color // +arg background =type Int =desc A background color, or [[nil]] if none // +arg result =type Bitmap =desc the same bitmap // // //------------------ PROTO ----------------------------------------------------- bitmapText +Proto bitmapText =type fun Bitmap Int Int Int Str Font Int Int -> Bitmap =mode Function =pkg core.2d.font =impl mcy =link =desc This function draws a text in a bitmap on a single line. The actual meaning of x and y coordinates depends on the alignment flag: for example with ALIGN_RIGHT, x is the right coordinate of the text area. The function takes care of clipping. See [[bitmapTextU8]] for Utf-8 strings. // +arg bmp =type Bitmap =desc any bitmap // +arg x =type Int =desc horizontal position // +arg y =type Int =desc vertical position // +arg flag =type Int =desc a combination of ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT and ALIGN_TOP, ALIGN_BOTTOM, ALIGN_BASELINE, ALIGN_MIDDLE. Default is ALIGN_LEFT|ALIGN_TOP. // +arg text =type Str =desc A Latin string // +arg font =type Font =desc A font // +arg foreground =type Int =desc A foreground color // +arg background =type Int =desc A background color, or [[nil]] if none // +arg result =type Bitmap =desc the same bitmap // // //------------------ PROTO ----------------------------------------------------- fontPositionU8 +Proto fontPositionU8 =type fun Font Str Int -> Int =mode Function =pkg core.2d.font =impl mcy =link =desc You can use this function when displaying text on screen to find out which character in the text your mouse is pointing to. x is the position of the mouse, considering the text starts at 0. The function returns the index in the string. // +arg font =type Font =desc A font // +arg str =type Str =desc A Utf-8 string // +arg x =type Int =desc A pixel coordinate // +arg result =type Int =desc An index in the string // // //------------------ PROTO ----------------------------------------------------- fontPosition +Proto fontPosition =type fun Font Str Int -> Int =mode Function =pkg core.2d.font =impl mcy =link =desc You can use this function when displaying text on screen to find out which character in the text your mouse is pointing to. x is the position of the mouse, considering the text starts at 0. The function returns the index in the string. // +arg font =type Font =desc A font // +arg str =type Str =desc A Latin string // +arg x =type Int =desc A pixel coordinate // +arg result =type Int =desc An index in the string // // //------------------ PROTO ----------------------------------------------------- fontStringWidthU8 +Proto fontStringWidthU8 =type fun Font Str -> Int =mode Function =pkg core.2d.font =impl mcy =link =desc This function returns the width of a string (in pixels) when displayed with a specific font. // +arg font =type Font =desc A font // +arg str =type Str =desc An utf-8 string // +arg result =type Int =desc An integer // // //------------------ PROTO ----------------------------------------------------- fontStringWidth +Proto fontStringWidth =type fun Font Str -> Int =mode Function =pkg core.2d.font =impl mcy =link =desc This function returns the width of a string (in pixels) when displayed with a specific font. // +arg font =type Font =desc A font // +arg str =type Str =desc A Latin string // +arg result =type Int =desc An integer // // //------------------ PROTO ----------------------------------------------------- fontStringMultilineHeightU8 +Proto fontStringMultilineHeightU8 =type fun Font Str Int -> Int =mode Function =pkg core.2d.font =impl mcy =link =desc This function returns the height in pixels of a multi-line text. Basically it calls [[fontStringMultilineU8]] and multiply the resulting number of lines by the font's height. // +arg font =type Font =desc A font // +arg str =type Str =desc An Utf-8 string // +arg w =type Int =desc A width in pixels // +arg result =type Int =desc A positive integer // // //------------------ PROTO ----------------------------------------------------- fontStringMultilineHeight +Proto fontStringMultilineHeight =type fun Font Str Int -> Int =mode Function =pkg core.2d.font =impl mcy =link =desc This function returns the height in pixels of a multi-line text. Basically it calls [[fontStringMultiline]] and multiply the resulting number of lines by the font's height. // +arg font =type Font =desc A font // +arg str =type Str =desc A Latin string // +arg w =type Int =desc A width in pixels // +arg result =type Int =desc A positive integer // // //------------------ PROTO ----------------------------------------------------- fontStringMultilineU8 +Proto fontStringMultilineU8 =type fun Font Str Int -> list Str =mode Function =pkg core.2d.font =impl mcy =link =desc This function splits a string so that each substring can be displayed in a rectangle of width w. // +arg font =type Font =desc A font // +arg str =type Str =desc An Utf-8 string // +arg w =type Int =desc A width in pixels // +arg result =type list Str =desc A list of strings // // //------------------ PROTO ----------------------------------------------------- fontStringMultiline +Proto fontStringMultiline =type fun Font Str Int -> list Str =mode Function =pkg core.2d.font =impl mcy =link =desc This function splits a string so that each substring can be displayed in a rectangle of width w. // +arg font =type Font =desc A font // +arg str =type Str =desc A Latin string // +arg w =type Int =desc A width in pixels // +arg result =type list Str =desc A list of strings // // //------------------ PROTO ----------------------------------------------------- fontH +Proto fontH =type fun Font -> Int =mode Function =pkg core.2d.font =impl mcy =link =desc This function returns the height in pixels of a font. // +arg font =type Font =desc A font // +arg result =type Int =desc An integer // // //------------------ PROTO ----------------------------------------------------- fontCharWidth +Proto fontCharWidth =type fun Font Int -> Int =mode Function =pkg core.2d.font =impl mcy =link =desc This function returns the width in pixels of a specific character in a font. It is the distance to respect before the next character in the flow. // +arg f =type Font =desc A font // +arg c =type Int =desc An ascii code (or unicode) // +arg result =type Int =desc A positive integer // // //------------------ PROTO ----------------------------------------------------- fontFixedFromBitmap +Proto fontFixedFromBitmap =type fun Bitmap Int Int Int -> Font =mode Function =pkg core.2d.font =impl mcy =link =desc This function creates a fixed-width [[Font]] from a bitmap. This bitmap is organized as a grid in which each glyph is in a rectangle of size w x h. Background must be black, glyphs may be gray: actually only the blue component is used and extended to gray scale. Glyph 0 is at the top left, glyph 1 is on the right and so on. When the end of a row is reached, next glyph is on the next row. You may have all the glyphs on one row, or split them on several rows. For example there is such a bitmap in ./rom/rsc/fonts/BOLD16x32.png In order to use this font with [[ALIGN_BASELINE]] the baseline position must be provided. It is the number of pixels below the baseline. > use core.2d.png;; > use core.2d.font;; > fontFixedFromBitmap (bitmapFromPng load "rsc/fonts/BOLD16x32.png") 16 32 6 // +arg bmp =type Bitmap =desc A bitmap with the specific format // +arg w =type Int =desc The width of each glyph // +arg h =type Int =desc The height of each glyph // +arg baseLine =type Int =desc The number of pixels below the baseline // +arg result =type Font =desc The resulting font // // //------------------ PROTO ----------------------------------------------------- fontFromBitmap +Proto fontFromBitmap =type fun Bitmap -> Font =mode Function =pkg core.2d.font =impl mcy =link =desc This function creates a variable-width [[Font]] from a bitmap. You may create and download such a bitmap with our [FontMaker online tool](https://minimacy.net/book/#/font_maker). This bitmap is organized in rows. It is assumed that each glyph has the same height 'h'. All rows have a height h+1. Background must be black. Let's consider a glyph whose drawing has width 'w': it will require a rectangle (w+1)x(h+1) - the top-left pixel is red - then the first row may contain green pixels to identify the glyph overflow - and the first column may contain at most one green pixel which identifies the baseline - the glyph itself is in the w x h area starting on the second column, second row. It may be gray: actually only the blue component is used and extended to gray scale. In the following example, we can see that the 'j' glyph is only 6 pixels width (6 black pixels on the first row), but overlaps left and right by several pixels (green pixels). [](html) As the baseline is the same for all glyphs, its green pixel is required only for the first glyph. Glyph 0 is at the top left, glyph 1 is on the right and so on. When the end of a row is reached, next glyph is on the next row. You may have all the glyphs on one row, or split them on several rows. For example there is such a bitmap in ./rom/rsc/fonts/Arial_32_256.png > use core.2d.png;; > use core.2d.font;; > fontFromBitmap (bitmapFromPng (load ("rsc/fonts/Arial_32_256.png"))) // +arg bmp =type Bitmap =desc A bitmap with the specific format // +arg result =type Font =desc The resulting font // // //------------------ PROTO ----------------------------------------------------- Font +Proto Font =type Font =mode structure =pkg core.2d.font =impl mcy =link =desc The type for fonts. // // //------------------ PROTO ----------------------------------------------------- ALIGN_MIDDLE +Proto ALIGN_MIDDLE =type Int =mode constant =pkg core.2d.font =impl mcy =link =desc Vertical alignment flag to use with [[bitmapText]], [[bitmapTextU8]], [[bitmapMultiLineText]], [[bitmapMultiLineTextU8]] // // //------------------ PROTO ----------------------------------------------------- ALIGN_BASELINE +Proto ALIGN_BASELINE =type Int =mode constant =pkg core.2d.font =impl mcy =link =desc Vertical alignment flag to use with [[bitmapText]], [[bitmapTextU8]], [[bitmapMultiLineText]], [[bitmapMultiLineTextU8]] // // //------------------ PROTO ----------------------------------------------------- ALIGN_BOTTOM +Proto ALIGN_BOTTOM =type Int =mode constant =pkg core.2d.font =impl mcy =link =desc Vertical alignment flag to use with [[bitmapText]], [[bitmapTextU8]], [[bitmapMultiLineText]], [[bitmapMultiLineTextU8]] // // //------------------ PROTO ----------------------------------------------------- ALIGN_TOP +Proto ALIGN_TOP =type Int =mode constant =pkg core.2d.font =impl mcy =link =desc Vertical alignment flag to use with [[bitmapText]], [[bitmapTextU8]], [[bitmapMultiLineText]], [[bitmapMultiLineTextU8]] // // //------------------ PROTO ----------------------------------------------------- ALIGN_CENTER +Proto ALIGN_CENTER =type Int =mode constant =pkg core.2d.font =impl mcy =link =desc Horizontal alignment flag to use with [[bitmapText]], [[bitmapTextU8]], [[bitmapMultiLineText]], [[bitmapMultiLineTextU8]] // // //------------------ PROTO ----------------------------------------------------- ALIGN_RIGHT +Proto ALIGN_RIGHT =type Int =mode constant =pkg core.2d.font =impl mcy =link =desc Horizontal alignment flag to use with [[bitmapText]], [[bitmapTextU8]], [[bitmapMultiLineText]], [[bitmapMultiLineTextU8]] // // //------------------ PROTO ----------------------------------------------------- ALIGN_LEFT +Proto ALIGN_LEFT =type Int =mode constant =pkg core.2d.font =impl mcy =link =desc Horizontal alignment flag to use with [[bitmapText]], [[bitmapTextU8]], [[bitmapMultiLineText]], [[bitmapMultiLineTextU8]]