User Tools

Site Tools


en:orx:config:settings_structure:orxtext

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
en:orx:config:settings_structure:orxtext [2011/05/16 16:49 (13 years ago)] – Updated to variable width font iarwainen:orx:config:settings_structure:orxtext [2023/08/25 01:09 (7 months ago)] (current) – [Details] sausage
Line 6: Line 6:
  
 <code ini>[TextTemplate] <code ini>[TextTemplate]
 +String = "string to display"
 Font   = FontTemplate Font   = FontTemplate
-String = <string></code>+</code>
  
 === Font === === Font ===
  
-<code ini>[FontTemplate] +<code ini> 
-Texture           = path/to/ImageFile +[FontTemplate] 
-TextureCorner     = <vector> +Texture            = path/to/ImageFile.ext 
-TextureSize       = <vector> +TextureOrigin      = <vector> 
-CharacterList     = <string+TextureSize        = <vector> 
-CharacterSpacing  <vector> +KeepInCache        = <bool
-CharacterSize     = <vector> +CharacterList      "ordered list of character" 
-CharacterHeight   = <float> +CharacterSize      = <vector> 
-CharacterWidthList= <float> <float...</code>+CharacterHeight    = <float> 
 +CharacterWidthList = <float> 
 +CharacterSpacing   <vector> 
 +</code>
  
 ==== Details ==== ==== Details ====
Line 26: Line 30:
  
 Here's a list of available properties for an ''orxTEXT'' structure: Here's a list of available properties for an ''orxTEXT'' structure:
-  * ''Font'': Specifies a font to use for this text. If no value is specified, orx's default font ((Dina, an open source font by Jørgen 'Jibs' Ibsen)) will be used. **NB: If its value begins with a dollar ('$')the rest of the value will be used as a key for the [[en:orx:config:settings_main:main#Locale localization module|localization module]].** + 
-  * ''String'': Defines the content of this orxTEXT as plain text**NB: If its value begins with a dollar ('$'), the rest of the value will be used as key for the [[en:orx:config:settings_main:main#Locale localization module|localization module]].**+  * ''String'': Defines the content of this orxTEXT as plain text. If this string begins with the character '$', it will be used as a locale key instead of as a plain text. It will then be automatically updated upon a new language selection. 
 +  * ''Font'': Specifies a font to use for this text. If none is provided or 'default' is used, orx's default font will be used. If it begins with the character '$', it will be used as a [[en:orx:config:settings_main:main#Locale localization module|locale key]] instead of as plain section nameIt will then be automatically updated upon new language selection. See below for an example of multiline text.
  
 Here's a small example. Here's a small example.
Line 37: Line 42:
 [Text2] [Text2]
 String = $Greetings String = $Greetings
-Font   = $FontKey</code>+Font   = $FontKey 
 + 
 +[MultilineText] 
 +String = "First line 
 +Second line" 
 +Font   = Font1</code>
  
 ''Text1'' has a static plain text content with a static custom font called ''Font1'' whereas ''Text2'' points to the localization keys named ''Greetings'' for its text content and ''FontKey'' for its font. This means that its content and font are defined in the [[en:orx:config:settings_main:main#Locale localization module|orxLOCALE module]] and will always be expressed according to the current selected language. ''Text1'' has a static plain text content with a static custom font called ''Font1'' whereas ''Text2'' points to the localization keys named ''Greetings'' for its text content and ''FontKey'' for its font. This means that its content and font are defined in the [[en:orx:config:settings_main:main#Locale localization module|orxLOCALE module]] and will always be expressed according to the current selected language.
Line 46: Line 56:
  
 Here's a list of available properties for an ''orxFONT'' structure: Here's a list of available properties for an ''orxFONT'' structure:
-  * ''Texture'': Specifies which bitmap file to use as texture for our font object. + 
-  * ''TextureCorner'': Specifies the top left corner of the first defined character in the bitmap file, in pixels (Z coordinate being ignored). By default its value is (0, 0, 0) which means the texture for the font object will begin at the top left of the bitmap file.+  * ''TextureOrigin'': Specifies the top left origin of the first defined character in the bitmap file, in pixels (Z coordinate being ignored). By default its value is (0, 0, 0) which means the texture for the font object will begin at the top left of the bitmap file. Note: TextureSize must also be supplied for this to take effect.
   * ''TextureSize'': Specifies the size, in pixels, of the bitmap file where characters are defined (Z coordinate being ignored). By default it will use the whole bitmap, ie. its value will be the size of the bitmap.   * ''TextureSize'': Specifies the size, in pixels, of the bitmap file where characters are defined (Z coordinate being ignored). By default it will use the whole bitmap, ie. its value will be the size of the bitmap.
-  * ''CharacterList'': Specifies all the characters that are defined in the bitmap file, ie. all the characters with a glyph in the texture file will have to be specified in order of appearance. The string can be encoded in strict ANSI or UTF-8. **ISO-Latin-1 is __not__ supported!** To avoid special characters to be handled by orx's config parser ((such as '#', ';', '"', '~', '$', ...)), the string is likely to be defined as a block using the block marker ('"'). **In order to specify '"' itself in the string, this character needs to be doubled!** +  * ''KeepInCache'': If true, the associated texture will always stay in cache. Defaults to false. 
-  * ''CharacterSpacing'': A vector specifying the empty spaces between characters, in pixels (Z coordinate being ignored). +  * ''CharacterList'': Specifies all the characters that are defined in the bitmap file, ie. all the characters with a glyph in the texture file will have to be specified in order of appearance. The string can be encoded in strict ANSI/ASCII or UTF-8. **ISO-Latin-1 is __not__ supported!** To avoid special characters to be handled by orx's config parser ((such as '#', ';', '"', '~', '$', ...)), the string is likely to be defined as a block using the block marker ('"'). **In order to specify '"' itself in the string, this character needs to be doubled and not in the first position!** 
-  * ''CharacterSize'': A vector specifying the size of a character, in pixels (Z coordinate being ignored). **If this property is defined, orx assumes the font is monospaced (ie. fixed width, all the characters need to be organized in a grid manner). See the command line tool [[#orxFontGen]] to see how to create custom bitmap fonts from a given TrueType font file.** +  * ''CharacterSize'': A vector specifying the size of a character, in pixels (Z coordinate being ignored). **If this property is defined, orx assumes the font is monospaced (ie. fixed width, all the characters need to be organized in a grid manner). See the command line tool [[#orxFontGen]] to see how to create custom bitmap fonts from a given TrueType font file.** If defined, CharacterHeight & CharacterWidthList will be ignored.  
-  * ''CharacterHeight'': This is only used for variable width fonts, ie. when ''CharacterSize'' is **not** defined. In this case, this property has to be a strictly positive value that will be the font character's height. +  * ''CharacterHeight'': This is only used for non-monospaced fonts, ie. when CharacterSize isn'defined. This property has to be a strictly positive value that will be the font character's height. 
-  * ''CharacterWidthList'': Only used for variable width fonts, ie. when ''CharacterSize'' is **not** defined. In this case, this contains a list of widths for every character defined in ''CharacterList'' in the same order.+  * ''CharacterWidthList'': This is only used for non-monospaced fonts, ie. when CharacterSize isn'defined. There should be exactly one value per character defined in CharacterList in the same order. 
 +  * ''CharacterSpacing'': Empty space between characters, z is ignored. Defaults to (0, 0, 0). 
 + 
 +An example of how to use custom fonts can be found in the [[en:tutorials:localization:locale|localization]] tutorial ((at the end of 10_Locale.ini)).
  
-An example of how to use custom fonts can be found in the [[en:orx:tutorials:standalone|stand alone/localization]] tutorial ((at the end of 10_StandAlone.ini)). 
 ===== orxFontGen ===== ===== orxFontGen =====
  
-orxFontGen is a command line tool that creates orx-formatted custom bitmap fonts (both .tga texture and .ini config file).\\ +orxFontGen is a command-line tool that ships with Orx which allows you create bitmap fonts which can be define with the configuration detailed above. It can be found in the orx/tools/orxFontGen/bin folderAvailable to compile for WindowsLinux and MacTo learn how to use it follow the [[en:tutorials:text-fonts:orxfontgen|orxFontGen tutorial]].
-It gathers the needed characters from the given text files and print them, at the requested size, from a TrueType font file. +
- +
-orxFontGen is available for all supported development platforms. ((Windows, Linux, Mac OS X)) +
- +
-It is based on the open source [[http://www.freetype.org/|FreeType library]]. +
- +
-**NB: orxFontGen currently only outputs bitmaps in .tga format. However, depending on the platform/plugin (for nowonly on iPhone), .tga might not be loaded by orx and need to be manually converted to .png (which is supported by all plugins).\\ +
-When doing such a conversion, don't forget to update the .ini file with the new bitmap name (usually replacing .tga with .png).\\ +
-Even if .tga loading is supported, it is advised to convert the .tga bitmap to a .png format which is more compact.** +
- +
-orxFontGen accepts a number of command line parameters: +
-  * [MANDATORY] a list of input text files to gather the needed characters +
-  * [MANDATORY] a TrueType font file ((usually .ttf)) +
-  * [MANDATORY] a size for characters to print, in pixels +
-  * [OPTIONAL]  a name for the custom font to output +
- +
-Here's its syntax: +
- +
-<code dos>orxfontgen -t TextFile [+ ...] -f FontFile -s Size [-o OutputName]</code> +
- +
-You can display its help with +
- +
-<code dos>orxfontgen -h</code> +
- +
-For any parameter, help can be diplayed using its long name: +
- +
-<code dos>orxfontgen -h ParameterLongName</code> +
- +
-Let's now see the parameters in details. +
- +
-==== Input text file list ==== +
- +
-**-t / ''-''''-''textlist** +
- +
-The text file list is mandatory. At least one file has to be provided and multiple files have to be separated by spaces. Unfortunately names of input text files can't include spaces for now.\\ +
-These files contains all the texts you want to display using this custom bitmal fontthe needed characters will be extracted from them. They should be encoded either in plain ASCII or in UTF-8. +
- +
-Syntax: +
- +
-<code dos>-t TextFile1 [TextFile2 ... TextFileN]</code> +
- +
-If input files are encrypted with a user-provided key, you need to pass it to orxcrypt using its [[#Encryption key|encryption key parameter]]. +
- +
-==== TrueType font file ==== +
- +
-**-f / ''-''''-''font** +
- +
-The TrueType font file parameter is mandatory. It defines the TrueType font file ((usually .ttf)) to use for creating the custom bitmap font. +
- +
-Syntax: +
- +
-<code dos>-f FontFile</code> +
- +
-==== Size ==== +
- +
-**-s / ''-''''-''size** +
- +
-The size parameter is mandatory. It defined the size, in pixels, for the printed characters in the custom bitmap font. +
- +
-Syntax: +
- +
-<code dos>-s Size</code>+
  
-==== Output name ==== 
  
-**-o / ''-''''-''output**+==== Latest config settings for the Development Version ==== 
 +{{section>en:orx:config:developmentversion#&noheader&nofooter&noeditbutton}}
  
-The output parameter is optional. If none is provided, the custom bitmap font will be stored in orxFont.tga/orxFont.ini.\\ 
en/orx/config/settings_structure/orxtext.1305589789.txt.gz · Last modified: 2017/05/30 00:50 (7 years ago) (external edit)