diff --git a/doc/xorg-docs/Makefile.bsd-wrapper b/doc/xorg-docs/Makefile.bsd-wrapper index 3bf1dd5d8..b3560cbe7 100644 --- a/doc/xorg-docs/Makefile.bsd-wrapper +++ b/doc/xorg-docs/Makefile.bsd-wrapper @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.bsd-wrapper,v 1.3 2019/04/30 21:37:43 schwarze Exp $ +# $OpenBSD: Makefile.bsd-wrapper,v 1.4 2019/05/02 19:12:04 schwarze Exp $ CONFIGURE_ARGS += --without-fop --without-xmlto @@ -13,12 +13,7 @@ beforeinstall: # maintainer target, not used duing build or install mdoc: .for n in ${MDOCS} - { \ - echo ".\\\" automatically generated with"; \ - echo ".\\\" docbook2mdoc ${n:T}.xml > ${n:T}.7"; \ - docbook2mdoc ${.CURDIR}/${n}.xml; \ - } > ${.CURDIR}/${n}.7 - sed -i 's/^\.Dt ${n:T:U} 1$$/.Dt ${n:T:U} 7/' ${.CURDIR}/${n}.7 + docbook2mdoc -s 7 ${.CURDIR}/${n}.xml > ${.CURDIR}/${n}.7 .endfor .include diff --git a/doc/xorg-docs/general/fonts/fonts.7 b/doc/xorg-docs/general/fonts/fonts.7 index 7075a2f5a..de6063f5a 100644 --- a/doc/xorg-docs/general/fonts/fonts.7 +++ b/doc/xorg-docs/general/fonts/fonts.7 @@ -1,5 +1,4 @@ -.\" automatically generated with -.\" docbook2mdoc fonts.xml > fonts.7 +.\" automatically generated with docbook2mdoc fonts.xml .Dd 16 March 2012 .Dt FONTS 7 .Os @@ -13,7 +12,8 @@ is aimed at the casual user wishing to install fonts in X11R6 the rest of the document describes the font support in more detail. .Pp -We assume some familiarity with digital fonts. If anything is not +We assume some familiarity with digital fonts. +If anything is not clear to you, please consult .Sx Appendix_background_and_terminology at the @@ -26,15 +26,18 @@ X11 that are not based on either XFree86 or X11R6.8 or later. .Pp The core X11 fonts system is directly derived from the fonts system included with X11R1 in 1987, which could only use monochrome bitmap -fonts. Over the years, it has been more or less happily coerced into +fonts. +Over the years, it has been more or less happily coerced into dealing with scalable fonts and rotated glyphs. .Pp Xft was designed from the start to provide good support for scalable -fonts, and to do so efficiently. Unlike the core fonts system, it +fonts, and to do so efficiently. +Unlike the core fonts system, it supports features such as anti-aliasing and sub-pixel rasterisation. Perhaps more importantly, it gives applications full control over the way glyphs are rendered, making fine typesetting and WYSIWIG display -possible. Finally, it allows applications to use fonts that are not +possible. +Finally, it allows applications to use fonts that are not installed system-wide for displaying documents with embedded fonts. .Pp Xft is not compatible with the core fonts system: usage of Xft @@ -48,7 +51,8 @@ system to access newly-installed fonts. .Ss Configuring Xft Xft has no configuration mechanism itself, it relies upon the .Lk http://www.fontconfig.org/ fontconfig -library to configure and customise fonts. That library is +library to configure and customise fonts. +That library is not specific to the X Window system, and does not rely on any particular font output mechanism. .Pp @@ -68,7 +72,8 @@ $ cp lucbr.ttf ~/.fonts/ .Ed .Pp Fontconfig will notice the new font at the next opportunity and rebuild its -list of fonts. If you want to trigger this update from the command +list of fonts. +If you want to trigger this update from the command line, you may run the command .Dq Nm fc-cache . .Bd -literal @@ -120,7 +125,8 @@ can be done with the following syntax: .Ed .Pp Another useful option is the ability to disable anti-aliasing (font -smoothing) for selected fonts. This can be done with the following +smoothing) for selected fonts. +This can be done with the following syntax: .Bd -literal @@ -142,7 +148,8 @@ Anti-aliasing can be disabled for all fonts by the following incantation: .Ed .Pp -Xft supports sub-pixel rasterisation on LCD displays. X11R6 should +Xft supports sub-pixel rasterisation on LCD displays. +X11R6 should automatically enable this feature on laptops and when using an LCD monitor connected with a DVI cable; you can check whether this was done by typing @@ -182,7 +189,8 @@ counterclockwise). .Sy Configuring applications .Pp A growing number of applications use Xft in preference to the core -fonts system. Some applications, however, need to be explicitly +fonts system. +Some applications, however, need to be explicitly configured to use Xft. .Pp A case in point is XTerm, which can be set to use Xft by using the @@ -211,11 +219,13 @@ anti-aliasing in case it was disabled by your Xft configuration file. .Pp Gnome applications and Mozilla Firefox will use Xft by default. .Ss Configuring the core X11 fonts system -Installing fonts in the core system is a two step process. First, +Installing fonts in the core system is a two step process. +First, you need to create a .Em font directory that contains all the -relevant font files as well as some index files. You then need to +relevant font files as well as some index files. +You then need to inform the X server of the existence of this new directory by including it in the .Em font path . @@ -226,9 +236,11 @@ The X11R6 server can use bitmap fonts in both the cross-platform BDF format and the somewhat more efficient binary PCF format. (X11R6 also supports the obsolete SNF format.) .Pp -Bitmap fonts are normally distributed in the BDF format. Before +Bitmap fonts are normally distributed in the BDF format. +Before installing such fonts, it is desirable (but not absolutely necessary) -to convert the font files to the PCF format. This is done by using the +to convert the font files to the PCF format. +This is done by using the command .Dq Nm bdftopcf , .Em e.g. @@ -279,7 +291,8 @@ to create an index file called There is, however, a big difference: .Dq Nm mkfontdir cannot -automatically recognise scalable font files. For that reason, you +automatically recognise scalable font files. +For that reason, you must first index all the font files in a file called .Pa fonts.scale . While this can be done by hand, it is best done @@ -307,7 +320,8 @@ later in this document. .Sy CID-keyed fonts .Pp The CID-keyed font format was designed by Adobe Systems for fonts -with large character sets. The CID-keyed format is obsolete, as it +with large character sets. +The CID-keyed format is obsolete, as it has been superseded by other formats such as OpenType/CFF and support for CID-keyed fonts has been removed from X11. .Pp @@ -321,14 +335,16 @@ font directory consists of putting it on the font path. .Pp The font path is an ordered list; if a client's request matches multiple fonts, the first one in the font path is the one that gets -used. When matching fonts, the server makes two passes over the font +used. +When matching fonts, the server makes two passes over the font path: during the first pass, it searches for an exact match; during the second, it searches for fonts suitable for scaling. .Pp For best results, scalable fonts should appear in the font path before the bitmap fonts; this way, the server will prefer bitmap fonts to scalable fonts when an exact match is possible, but will avoid scaling -bitmap fonts when a scalable font can be used. (The +bitmap fonts when a scalable font can be used. +(The .Dq Li :unscaled hack, while still supported, should no longer be necessary in X11R6.) .Pp @@ -349,7 +365,8 @@ added as a local font path entry. The symlink can be suffixed by attributes such as .Pf ' Ql unscaled Ns ', which will be passed through -to the underlying font path entry. The only exception is the newly +to the underlying font path entry. +The only exception is the newly introduced .Pf ' Ql pri Ns ' attribute, which will be @@ -384,7 +401,8 @@ setting the following font path: The .Dq Nm xset utility may be used to modify the font path for the -current session. The font path is set with the command +current session. +The font path is set with the command .Nm xset fp ; a new element is added to the front with .Nm xset +fp , @@ -417,12 +435,14 @@ after may be specified in the X server's .Pa xorg.conf -file. It is computed by appending all the +file. +It is computed by appending all the directories mentioned in the .Dq Li FontPath entries of the .Dq Li Files -section in the order in which they appear. If no font path is specified in a config file, the server uses a default +section in the order in which they appear. +If no font path is specified in a config file, the server uses a default value specified when it was built. .Bd -literal FontPath "/usr/local/fonts/Type1" @@ -446,11 +466,13 @@ this doesn't help, it is quite possible that you are trying to use a font in a format that is not supported by your server. .Pp X11R6 supports the BDF, PCF, SNF, Type 1, TrueType, and OpenType -font formats. However, not all X11R6 servers +font formats. +However, not all X11R6 servers come with all the font backends configured in. .Pp On most platforms, the X11R6 servers no longer uses font -backends from modules that are loaded at runtime. The built in +backends from modules that are loaded at runtime. +The built in font support corresponds to the functionality formerly provided by these modules: .Bl -bullet @@ -486,7 +508,8 @@ family, and bitmap versions of Courier, Times, Helvetica and some members of the Lucida family. .Pp In X11R6, a number of these fonts are provided in Unicode-encoded -font files now. At build time, these fonts are split into font +font files now. +At build time, these fonts are split into font files encoded according to legacy encodings, a process which allows us to provide the standard fonts in a number of regional encodings with no duplication of work. @@ -505,7 +528,8 @@ is a Unicode-encoded version of the standard .Dq Li fixed font with added support for the Latin, Greek, Cyrillic, Georgian, Armenian, IPA -and other scripts plus numerous technical symbols. It contains over +and other scripts plus numerous technical symbols. +It contains over 2800 glyphs, covering all characters of ISO\ 8859 parts 1-5, 7-10, 13-15, as well as all European IBM and Microsoft code pages, KOI8, WGL4, and the repertoires of many other character sets. @@ -536,7 +560,8 @@ is normally an alias for .Ss The ClearlyU Unicode font family The ClearlyU family of fonts provides a set of 12\ pt, 100\ dpi proportional fonts with many of the glyphs needed for -Unicode text. Together, the fonts contain approximately 7500 glyphs. +Unicode text. +Together, the fonts contain approximately 7500 glyphs. .Pp The main ClearlyU font has the XLFD .Bd -literal @@ -559,7 +584,8 @@ Additional ClearlyU fonts include The .Em Alternate Glyphs font contains additional glyph shapes that -are needed for certain languages. A second alternate glyph font will +are needed for certain languages. +A second alternate glyph font will be provided later for cases where a character has more than one commonly used alternate shape .Pf ( Em e.g. @@ -574,7 +600,8 @@ The .Em Arabic Extra font contains the glyphs necessary for characters that don't have all of their possible shapes encoded in -ISO\ 10646. The glyphs are roughly ordered according to the order +ISO\ 10646. +The glyphs are roughly ordered according to the order of the characters in the ISO\ 10646 standard. .Pp The @@ -587,7 +614,8 @@ X11R6 includes all the scalable fonts distributed with X11R6. .Sy Standard Type\e1 fonts .Pp The IBM Courier set of fonts cover ISO\ 8859-1 and -ISO\ 8859-2 as well as Adobe Standard Encoding. These fonts have +ISO\ 8859-2 as well as Adobe Standard Encoding. +These fonts have XLFD .Bd -literal -adobe-courier-medium-*-*--0-0-0-0-m-0-*-* @@ -599,7 +627,8 @@ and reside in the font files .Ed .Pp The Adobe Utopia set of fonts only cover ISO\ 8859-1 as well as -Adobe Standard Encoding. These fonts have XLFD +Adobe Standard Encoding. +These fonts have XLFD .Bd -literal -adobe-utopia-*-*-normal--0-0-0-0-p-0-iso8859-1 .Ed @@ -610,7 +639,8 @@ and reside in the font files .Ed .Pp Finally, X11R6 also comes with Type\ 1 versions of Bitstream -Courier and Charter. These fonts have XLFD +Courier and Charter. +These fonts have XLFD .Bd -literal -bitstream-courier-*-*-normal--0-0-0-0-m-0-iso8859-1 -bitstream-charter-*-*-normal--0-0-0-0-p-0-iso8859-1 @@ -624,7 +654,8 @@ and reside in the font files X11R6 includes the .Em Luxi family of scalable fonts, in both -TrueType and Type\ 1 format. This family consists of the fonts +TrueType and Type\ 1 format. +This family consists of the fonts .Em Luxi Serif , with XLFD .Bd -literal @@ -648,7 +679,8 @@ Each of these fonts comes Roman, oblique, bold and bold oblique variants The TrueType version have glyphs covering the basic ASCII Unicode range, the Latin\ 1 range, as well as the .Em Extended Latin -range and some additional punctuation characters. In particular, +range and some additional punctuation characters. +In particular, these fonts include all the glyphs needed for ISO\ 8859 parts 1, 2, 3, 4, 9, 13 and 15, as well as all the glyphs in the Adobe Standard encoding and the Windows 3.1 character set. @@ -658,8 +690,10 @@ and only covers ISO\ 8859 parts 1, 2 and 15 as well as the Adobe Standard encoding. .Pp The Luxi fonts are original designs by Kris Holmes and Charles -Bigelow. Luxi fonts include seriffed, sans serif, and monospaced -styles, in roman and oblique, and normal and bold weights. The fonts +Bigelow. +Luxi fonts include seriffed, sans serif, and monospaced +styles, in roman and oblique, and normal and bold weights. +The fonts share stem weight, x-height, capital height, ascent and descent, for graphical harmony. .Pp @@ -720,7 +754,8 @@ Two of the scalable backends (Type\ 1 and the TrueType backend) use a common .Em fontenc layer for -font re-encoding. This allows these backends to share their encoding +font re-encoding. +This allows these backends to share their encoding data, and allows simple configuration of new locales independently of font type. .Pp @@ -734,7 +769,8 @@ In the layer, an encoding is defined by a name (such as .Ql iso8859-1 ) , possibly a number of aliases (alternate names), and -an ordered collection of mappings. A mapping defines the way the +an ordered collection of mappings. +A mapping defines the way the encoding can be mapped into one of the .Em target encodings known to @@ -747,7 +783,8 @@ A number of encodings are hardwired into .Em fontenc , and are therefore always available; the hardcoded encodings cannot easily be -redefined. These include: +redefined. +These include: .Bl -bullet .It .Ql iso10646-1 : @@ -827,14 +864,16 @@ file named .Pa encodings.dir . If found, this file is scanned for the requested encoding, and the relevant encoding definition file is -read in. The +read in. +The .Dq Nm mkfontdir utility, when invoked with the .Dq Li -e option followed by the name of a directory containing encoding files, can be used to automatically build .Pa encodings.dir -files. Please see the +files. +Please see the .Lk mkfontdir.1.html mkfontdir(1) manual page for more details. .Pp @@ -850,21 +889,26 @@ later in this document. .Sy The FreeType backend .Pp For TrueType and OpenType fonts, the FreeType backend scans the -mappings in order. Mappings with a target of PostScript are ignored; +mappings in order. +Mappings with a target of PostScript are ignored; mappings with a TrueType or Unicode target are checked against all the -cmaps in the file. The first applicable mapping is used. +cmaps in the file. +The first applicable mapping is used. .Pp For Type\ 1 fonts, the FreeType backend first searches for a -mapping with a target of PostScript. If one is found, it is used. +mapping with a target of PostScript. +If one is found, it is used. Otherwise, the backend searches for a mapping with target Unicode, which is then composed with a built-in table mapping codes to glyph -names. Note that this table only covers part of the Unicode code +names. +Note that this table only covers part of the Unicode code points that have been assigned names by Adobe. .Pp Specifying an encoding value of .Ql adobe-fontspecific for a -Type\ 1 font disables the encoding mechanism. This is useful with +Type\ 1 font disables the encoding mechanism. +This is useful with symbol and incorrectly encoded fonts (see .Sx Hints_about_using_badly_encoded_fonts below). @@ -890,8 +934,10 @@ file has a similar format to Its first line specifies the number of encodings, while every successive line has two columns, the name of the encoding, and the name of the encoding file; this can be relative to the current -directory, or absolute. Every encoding name should agree with the -encoding name defined in the encoding file. For example, +directory, or absolute. +Every encoding name should agree with the +encoding name defined in the encoding file. +For example, .Bd -literal 3 mulearabic-0 /usr/share/fonts/X11/encodings/mulearabic-0.enc @@ -905,7 +951,8 @@ be specified in the encoding file's .Dq Li STARTENCODING or .Dq Li ALIAS -line. It is not enough to create +line. +It is not enough to create an .Pa encodings.dir entry. @@ -917,7 +964,8 @@ The .Pa encoding.dir files are best maintained by the .Dq Nm mkfontdir -utility. Please see the +utility. +Please see the .Lk mkfontdir.1.html mkfontdir(1) manual page for more information. .Pp @@ -927,7 +975,8 @@ The encoding files are .Dq free form, .Em i.e. any string of -whitespace is equivalent to a single space. Keywords are parsed in a +whitespace is equivalent to a single space. +Keywords are parsed in a non-case-sensitive manner, meaning that .Dq Li size , .Dq Li SIZE , @@ -965,15 +1014,18 @@ an XLFD font name, and therefore contain exactly one dash .Dq Li - . .Pp The encoding file may then optionally declare the size of the -encoding. For a linear encoding (such as ISO\ 8859-1), the SIZE +encoding. +For a linear encoding (such as ISO\ 8859-1), the SIZE line specifies the maximum code plus one: .Bd -literal SIZE 0x2B .Ed .Pp -For a matrix encoding, it should specify two numbers. The first is +For a matrix encoding, it should specify two numbers. +The first is the number of the last row plus one, the other, the highest column -number plus one. In the case of +number plus one. +In the case of .Dq Li jisx0208.1990-0 (JIS\ X\ 0208(1990), double-byte encoding, high bit clear), it should be @@ -984,7 +1036,8 @@ SIZE 0x75 0x80 In the case of a matrix encoding, a .Dq Li FIRSTINDEX line may be -included to specify the minimum glyph index in an encoding. The +included to specify the minimum glyph index in an encoding. +The keyword .Dq Li FIRSTINDEX is followed by two integers, the minimum row @@ -996,7 +1049,8 @@ FIRSTINDEX 0x20 0x20 In the case of a linear encoding, a .Dq Li FIRSTINDEX line is not very -useful. If for some reason however you chose to include on, it should +useful. +If for some reason however you chose to include on, it should be followed by a single integer. .Pp Note that in most font backends inclusion of a @@ -1009,11 +1063,13 @@ Codes outside the region defined by the .Dq Li SIZE and .Dq Li FIRSTINDEX -lines are understood to be undefined. Encodings +lines are understood to be undefined. +Encodings default to linear encoding with a size of 256 (0x100). This means that you must declare the size of all 16 bit encodings. .Pp -What follows is one or more mapping sections. A mapping section +What follows is one or more mapping sections. +A mapping section starts with a .Dq Li STARTMAPPING line stating the target of the mapping. @@ -1038,7 +1094,8 @@ STARTMAPPING postscript .El .Pp Every line in a mapping section maps one from the encoding being -defined to the target of the mapping. In mappings with a Unicode or +defined to the target of the mapping. +In mappings with a Unicode or TrueType mapping, codes are mapped to codes: .Bd -literal 0x21 0x0660 @@ -1047,26 +1104,24 @@ TrueType mapping, codes are mapped to codes: .Ed .Pp As an abbreviation, it is possible to map a contiguous range of codes -in a single line. A line consisting of three integers +in a single line. +A line consisting of three integers .Bd -literal \[u003C]it/start/ \[u003C]it/end/ \[u003C]it/target/ .Ed .Pp is an abbreviation for the range of lines .Bd -literal -.Em start -.Em target +.Em start Em target .Ed .Bd -literal -.Em start Ns +1 -.Em target Ns +1 +.Em start Ns +1 Em target Ns +1 .Ed .Bd -literal \&... .Ed .Bd -literal -.Em end -.Em target Ns + Ns Em end Ns - Ns Em start +.Em end Em target Ns Pf + Em end Ns Pf - Em start .Ed .Pp For example, the line @@ -1098,7 +1153,8 @@ or, for a single code, UNDEFINE 0x1234 .Ed .Pp -PostScript mappings are different. Every line in a PostScript mapping +PostScript mappings are different. +Every line in a PostScript mapping maps a code to a glyph name .Bd -literal 0x41 A @@ -1137,7 +1193,8 @@ one of the .Ql microsoft-symbol and .Ql apple-roman -encodings. A +encodings. +A number of symbol fonts, however, are not marked as such; such fonts should be installed using .Ql microsoft-cp1252 , @@ -1146,7 +1203,8 @@ or, for older fonts, .Pp In order to guarantee consistent results (especially between Type\ 1 and TrueType versions of the same font), it is possible to -define a special encoding for a given font. This has already been done +define a special encoding for a given font. +This has already been done for the .Ql ZapfDingbats font; see the file @@ -1154,10 +1212,12 @@ font; see the file .Pp .Sy Hints about using badly encoded fonts .Pp -A number of text fonts are incorrectly encoded. Incorrect encoding +A number of text fonts are incorrectly encoded. +Incorrect encoding is sometimes done by design, in order to make a font for an exotic script appear like an ordinary Western text font on systems which are -not easily extended with new locale data. It is often the result of +not easily extended with new locale data. +It is often the result of the font designer's laziness or incompetence; for some reason, most people seem to find it easier to invent idiosyncratic glyph names rather than follow the Adobe glyph list. @@ -1173,7 +1233,8 @@ file. In the case of Type\ 1 fonts, the font designer can specify a default encoding; this encoding is requested by using the .Dq Li adobe-fontspecific -encoding in the XLFD name. Sometimes, the +encoding in the XLFD name. +Sometimes, the font designer omitted to specify a reasonable default encoding, in which case you should experiment with .Dq Li adobe-standard , @@ -1186,7 +1247,8 @@ and doesn't make sense for Type\ 1 fonts). .Pp -TrueType fonts do not have a default encoding. However, most TrueType +TrueType fonts do not have a default encoding. +However, most TrueType fonts are designed with either Microsoft or Apple platforms in mind, so one of .Dq Li microsoft-symbol , @@ -1200,7 +1262,8 @@ results. .Sy Specifying an ad hoc encoding file .Pp It is always possible to define an encoding file to put the glyphs -in a font in any desired order. Again, see the +in a font in any desired order. +Again, see the .Pa encodings/adobe-dingbats.enc file to see how this is done. .Pp @@ -1217,9 +1280,11 @@ remap them to their proper names. .Pp This is done by writing a .Pa fonts.alias -file. The format of this file +file. +The format of this file is very simple: it consists of a series of lines each mapping an alias -name to a font name. A +name to a font name. +A .Pa fonts.alias file might look as follows: .Bd -literal @@ -1267,7 +1332,8 @@ and .Pp In order to access the faces in a TrueType Collection file, the face number must be specified in the fonts.dir file before the filename, -within a pair of colons, or by setting the 'fn' TTCap option. For example, +within a pair of colons, or by setting the 'fn' TTCap option. +For example, .Bd -literal :1:mincho.ttc -misc-pmincho-medium-r-normal--0-0-0-0-p-0-jisx0208.1990-0 .Ed @@ -1291,7 +1357,8 @@ general syntax option=value: .Ed .Pp -and should be specified before the filename. The new +and should be specified before the filename. +The new .Em FreeType almost perfectly supports TTCap options that are compatible with X-TT 1.4. The Automatic Italic @@ -1315,7 +1382,8 @@ bw=0.5:ds=y:ai=0.2:mincho.ttc -misc-mincho-bold-i-normal--0-0-0-0-c-0-jisx0201.1 .Ed .Pp setup the complete combination of jisx0208 and jisx0201 using mincho.ttc -only. More information on the TTCap syntax is found on +only. +More information on the TTCap syntax is found on .Lk http://x-tt.sourceforge.jp/ "the After X-TT Project page" . .Pp The @@ -1335,20 +1403,24 @@ When loading a proportional fonts which contain a huge number of glyphs, the old .Em FreeType delayed glyph rasterisation until the time at which -the glyph was first used. The new FreeType (libfreetype-xtt2) has an +the glyph was first used. +The new FreeType (libfreetype-xtt2) has an improved .Dq very lazy metric calculation method to speed up the process when -loading TrueType or OpenType fonts. Although the +loading TrueType or OpenType fonts. +Although the .Em X-TT module also has this method, the .Pf \(dq Ql vl=y Ns \(dq TTCap option must be set if you want to -use it. This is the default method for +use it. +This is the default method for .Em FreeType when it loads -multi-byte fonts. Even if you use a unicode font which has tens of +multi-byte fonts. +Even if you use a unicode font which has tens of thousands of glyphs, this delay will not be worrisome as long as you use the new .Em FreeType @@ -1359,16 +1431,19 @@ method is super-fast. The maximum error of bitmap position using .Dq very lazy method is 1 pixel, -and is the same as that of a character-cell spacing. When the X-TT +and is the same as that of a character-cell spacing. +When the X-TT backend is used with the .Dq Li vl=y option, a chipped bitmap is displayed -with certain fonts. However, the new FreeType backend has minimal problem +with certain fonts. +However, the new FreeType backend has minimal problem with this, since it corrects left- and right-side bearings using .Dq italicAngle in the TrueType/OpenType post table, and does automatic correction of bitmap positions when rasterisation so that chipped bitmaps -are not displayed. Nevertheless if you don't want to use the +are not displayed. +Nevertheless if you don't want to use the .Dq very lazy method when using multi-bytes fonts, set .Dq Li vl=n @@ -1393,7 +1468,8 @@ fs=c:mincho.ttc -misc-mincho-medium-r-normal--0-0-0-0-p-0-jisx0208.1990-0 .Ed .Pp will not compute the metric for each glyph, but instead -trust the font to be a character-cell font. You are +trust the font to be a character-cell font. +You are encouraged to make use of this optimisation when useful, but be warned that not all monospaced fonts are character-cell fonts. .Sh APPENDIX: BACKGROUND AND TERMINOLOGY @@ -1401,23 +1477,27 @@ that not all monospaced fonts are character-cell fonts. A computer text-processing system inputs keystrokes and outputs .Em glyphs , small pictures that are assembled on paper or on a -computer screen. Keystrokes and glyphs do not, in general, coincide: +computer screen. +Keystrokes and glyphs do not, in general, coincide: for example, if the system does generate ligatures, then to the sequence of two keystrokes .Pf < Ql f Ns > Ns < Ns Ql i Ns > will typically -correspond a single glyph. Similarly, if the system shapes Arabic +correspond a single glyph. +Similarly, if the system shapes Arabic glyphs in a vaguely reasonable manner, then multiple different glyphs may correspond to a single keystroke. .Pp The complex transformation rules from keystrokes to glyphs are usually factored into two simpler transformations, from keystrokes to .Em characters -and from characters to glyphs. You may want to think +and from characters to glyphs. +You may want to think of characters as the basic unit of text that is stored .Em e.g. in -the buffer of your text editor. While the definition of a character +the buffer of your text editor. +While the definition of a character is intrinsically application-specific, a number of standardised collections of characters have been defined. .Pp @@ -1427,7 +1507,8 @@ is a set of characters together with a mapping from integer codes --- known as .Em codepoints --- to -characters. Examples of coded character sets include US-ASCII, +characters. +Examples of coded character sets include US-ASCII, ISO\ 8859-1, KOI8-R, and JIS\ X\ 0208(1990). .Pp A coded character set need not use 8 bit integers to index characters. @@ -1465,8 +1546,10 @@ or and .Em OpenType . .Pp -The glyph data in a digital font needs to be indexed somehow. How -this is done depends on the font file format. In the case of +The glyph data in a digital font needs to be indexed somehow. +How +this is done depends on the font file format. +In the case of Type\ 1 fonts, glyphs are identified by .Em glyph names . In the @@ -1501,11 +1584,14 @@ of some fields: -adobe-courier-medium-r-normal--0-0-0-0-m-0-iso8859-1 .Ed .Pp -X11 font instances may also be specified by short name. Unlike an +X11 font instances may also be specified by short name. +Unlike an XLFD, a short name has no structure and is simply a conventional name -for a font instance. Two short names are of particular interest, as +for a font instance. +Two short names are of particular interest, as the server will not start if font instances with these names cannot be -opened. These are +opened. +These are .Dq Li fixed , which specifies the fallback font to use when the requested font cannot be opened, and @@ -1527,7 +1613,8 @@ Unicode .Pf ( Lk http://www.unicode.org http://www.unicode.org ) is a coded character set with the goal of uniquely identifying all characters for all -scripts, current and historical. While Unicode was explicitly not +scripts, current and historical. +While Unicode was explicitly not designed as a glyph encoding scheme, it is often possible to use it as such. .Pp @@ -1542,7 +1629,8 @@ meaning that it only defines glyphs for a subset of the character registry of Unicode. .Pp The Unicode standard is defined in parallel with the international -standard ISO\ 10646. Assignments in the two standards are always +standard ISO\ 10646. +Assignments in the two standards are always equivalent, and we often use the terms .Em Unicode and @@ -1554,7 +1642,8 @@ have the last two fields of their XLFD set to .Dq Li iso10646-1 . .Sh REFERENCES X11R6 comes with extensive documentation in the form of manual -pages and typeset documents. Before installing fonts, you really should +pages and typeset documents. +Before installing fonts, you really should read the .Lk fontconfig.3.html fontconfig(3) and diff --git a/lib/libdrm/Makefile.bsd-wrapper b/lib/libdrm/Makefile.bsd-wrapper index e1de6c40f..cbc6ca454 100644 --- a/lib/libdrm/Makefile.bsd-wrapper +++ b/lib/libdrm/Makefile.bsd-wrapper @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.bsd-wrapper,v 1.19 2019/04/28 20:47:20 schwarze Exp $ +# $OpenBSD: Makefile.bsd-wrapper,v 1.20 2019/05/02 19:12:05 schwarze Exp $ SHARED_LIBS= drm 7.7 drm_radeon 4.0 drm_intel 5.4 \ drm_amdgpu 1.8 drm_nouveau 3.0 @@ -15,11 +15,7 @@ beforeinstall: # maintainer target, not used duing build or install mdoc: .for n s in ${MDOCS} - { \ - echo ".\\\" automatically generated with"; \ - echo ".\\\" docbook2mdoc ${n}.xml > ${n}.${s}"; \ - docbook2mdoc ${.CURDIR}/man/${n}.xml; \ - } > ${.CURDIR}/man/${n}.${s} + docbook2mdoc ${.CURDIR}/man/${n}.xml > ${.CURDIR}/man/${n}.${s} .endfor .PHONY: mdoc diff --git a/lib/libdrm/man/drm-kms.7 b/lib/libdrm/man/drm-kms.7 index d3000b7d1..55c6ae160 100644 --- a/lib/libdrm/man/drm-kms.7 +++ b/lib/libdrm/man/drm-kms.7 @@ -1,5 +1,4 @@ -.\" automatically generated with -.\" docbook2mdoc drm-kms.xml > drm-kms.7 +.\" automatically generated with docbook2mdoc drm-kms.xml .Dd September 2012 .Dt DRM-KMS 7 .Os @@ -11,7 +10,8 @@ .Fd #include .Sh DESCRIPTION Each DRM device provides access to manage which monitors and displays -are currently used and what frames to be displayed. This task is +are currently used and what frames to be displayed. +This task is called .Em Kernel Mode-Setting (KMS). Historically, @@ -20,9 +20,11 @@ this was done in user-space and called (UMS). Almost all open-source drivers now provide the KMS kernel API to do this in the kernel, however, many non-open-source binary drivers from different -vendors still do not support this. You can use +vendors still do not support this. +You can use .Xr drmModeSettingSupported 3 -to check whether your driver supports this. To understand how KMS +to check whether your driver supports this. +To understand how KMS works, we need to introduce 5 objects: .Em CRTCs , .Em Planes , @@ -38,15 +40,19 @@ short for .Em CRT Controller is an abstraction representing a part of the chip that contains a pointer to a -scanout buffer. Therefore, the number of CRTCs available +scanout buffer. +Therefore, the number of CRTCs available determines how many independent scanout buffers can be active -at any given time. The CRTC structure contains several fields +at any given time. +The CRTC structure contains several fields to support this: a pointer to some video memory (abstracted as a frame-buffer object), a list of driven connectors, a display mode and an (x, y) offset into the video memory to support panning or configurations where one piece of video memory -spans multiple CRTCs. A CRTC is the central point where -configuration of displays happens. You select which objects to +spans multiple CRTCs. +A CRTC is the central point where +configuration of displays happens. +You select which objects to use, which modes and which parameters and then configure each CRTC via .Xr drmModeCrtcSet 3 @@ -56,11 +62,15 @@ A .Em plane respresents an image source that can be blended with or overlayed on top of a CRTC during the -scanout process. Planes are associated with a frame-buffer to +scanout process. +Planes are associated with a frame-buffer to crop a portion of the image memory (source) and optionally -scale it to a destination size. The result is then blended -with or overlayed on top of a CRTC. Planes are not provided by -all hardware and the number of available planes is limited. If +scale it to a destination size. +The result is then blended +with or overlayed on top of a CRTC. +Planes are not provided by +all hardware and the number of available planes is limited. +If planes are not available or if not enough planes are available, the user should fall back to normal software blending (via GPU or CPU). @@ -69,8 +79,10 @@ An .Em encoder takes pixel data from a CRTC and converts it to a format suitable for any attached -connectors. On some devices, it may be possible to have a CRTC -send data to more than one encoder. In that case, both +connectors. +On some devices, it may be possible to have a CRTC +send data to more than one encoder. +In that case, both encoders would receive data from the same scanout buffer, resulting in a .Em cloned @@ -82,8 +94,10 @@ A .Em connector is the final destination of pixel-data on a device, and usually connects directly to an -external display device like a monitor or laptop panel. A -connector can only be attached to one encoder at a time. The +external display device like a monitor or laptop panel. +A +connector can only be attached to one encoder at a time. +The connector is also the structure where information about the attached display is kept, so it contains fields for display data, @@ -99,11 +113,14 @@ modes supported on the attached displays. are abstract memory objects that provide a source of pixel data to scanout to a CRTC. Applications explicitly request the creation of framebuffers -and can control their behavior. Framebuffers rely on the +and can control their behavior. +Framebuffers rely on the underneath memory manager for low-level memory operations. When creating a framebuffer, applications pass a memory handle -through the API which is used as backing storage. The -framebuffer itself is only an abstract object with no data. It +through the API which is used as backing storage. +The +framebuffer itself is only an abstract object with no data. +It just refers to memory buffers that must be created with the .Xr drm-memory 7 API. @@ -114,7 +131,8 @@ Before mode-setting can be performed, an application needs to call to become .Em DRM-Master . It then has exclusive -access to the KMS API. A call to +access to the KMS API. +A call to .Xr drmModeGetResources 3 returns a list of .Em CRTCs , @@ -124,51 +142,67 @@ and .Em Planes . .Pp Normal procedure now includes: First, you select which connectors -you want to use. Users are mostly interested in which monitor or +you want to use. +Users are mostly interested in which monitor or display-panel is active so you need to make sure to arrange them in -the correct logical order and select the correct ones to use. For -each connector, you need to find a CRTC to drive this connector. If +the correct logical order and select the correct ones to use. +For +each connector, you need to find a CRTC to drive this connector. +If you want to clone output to two or more connectors, you may use a single CRTC for all cloned connectors (if the hardware supports this). To find a suitable CRTC, you need to iterate over the list of -encoders that are available for each connector. Each encoder +encoders that are available for each connector. +Each encoder contains a list of CRTCs that it can work with and you simply select -one of these CRTCs. If you later program the CRTC to control a -connector, it automatically selects the best encoder. However, this +one of these CRTCs. +If you later program the CRTC to control a +connector, it automatically selects the best encoder. +However, this procedure is needed so your CRTC has at least one working encoder -for the selected connector. See the +for the selected connector. +See the .Em Examples section below for more information. .Pp All valid modes for a connector can be retrieved with a call to .Xr drmModeGetConnector 3 -You need to select the mode you want to use and save it. The first +You need to select the mode you want to use and save it. +The first mode in the list is the default mode with the highest resolution possible and often a suitable choice. .Pp After you have a working connector+CRTC+mode combination, you need -to create a framebuffer that is used for scanout. Memory buffer +to create a framebuffer that is used for scanout. +Memory buffer allocation is driver-depedent and described in .Xr drm-memory 7 . -You need to create a buffer big enough for your selected mode. Now +You need to create a buffer big enough for your selected mode. +Now you can create a framebuffer object that uses your memory-buffer as -scanout buffer. You can do this with +scanout buffer. +You can do this with .Xr drmModeAddFB 3 and .Xr drmModeAddFB2 3 . .Pp As a last step, you want to program your CRTC to drive your selected -connector. You can do this with a call to +connector. +You can do this with a call to .Xr drmModeSetCrtc 3 . .Ss Page-Flipping A call to .Xr drmModeSetCrtc 3 is executed immediately and forces the CRTC to use the new scanout -buffer. If you want smooth-transitions without tearing, you probably -use double-buffering. You need to create one framebuffer object for -each buffer you use. You can then call +buffer. +If you want smooth-transitions without tearing, you probably +use double-buffering. +You need to create one framebuffer object for +each buffer you use. +You can then call .Xr drmModeSetCrtc 3 -on the next buffer to flip. If you want to synchronize your flips +on the next buffer to flip. +If you want to synchronize your flips with .Em vertical-blanks , you can use @@ -176,30 +210,41 @@ you can use which schedules your page-flip for the next .Em vblank . .Ss Planes -Planes are controlled independently from CRTCs. That is, a call to +Planes are controlled independently from CRTCs. +That is, a call to .Xr drmModeSetCrtc 3 -does not affect planes. Instead, you need to call +does not affect planes. +Instead, you need to call .Xr drmModeSetPlane 3 -to configure a plane. This requires the plane ID, a CRTC, a +to configure a plane. +This requires the plane ID, a CRTC, a framebuffer and offsets into the plane-framebuffer and the -CRTC-framebuffer. The CRTC then blends the content from the plane -over the CRTC framebuffer buffer during scanout. As this does not +CRTC-framebuffer. +The CRTC then blends the content from the plane +over the CRTC framebuffer buffer during scanout. +As this does not involve any software-blending, it is way faster than traditional -blending. However, plane resources are limited. See +blending. +However, plane resources are limited. +See .Xr drmModeGetPlaneResources 3 for more information. .Ss Cursors -Similar to planes, many hardware also supports cursors. A cursor is +Similar to planes, many hardware also supports cursors. +A cursor is a very small buffer with an image that is blended over the CRTC -framebuffer. You can set a different cursor for each CRTC with +framebuffer. +You can set a different cursor for each CRTC with .Xr drmModeSetCursor 3 and move it on the screen with .Xr drmModeMoveCursor 3 . -This allows to move the cursor on the screen without rerendering. If +This allows to move the cursor on the screen without rerendering. +If no hardware cursors are supported, you need to rerender for each frame the cursor is moved. .Sh EXAMPLES -Some examples of how basic mode-setting can be done. See the man-page +Some examples of how basic mode-setting can be done. +See the man-page of each DRM function for more information. .Ss CRTC/Encoder Selection If you retrieved all display configuration information via @@ -215,7 +260,8 @@ and retrieved the connector-information as via .Xr drmModeGetConnector 3 then this example shows, how you can find a suitable CRTC id to -drive this connector. This function takes a file-descriptor to the +drive this connector. +This function takes a file-descriptor to the DRM device (see .Xr drmOpen 3 ) as diff --git a/lib/libdrm/man/drm-memory.7 b/lib/libdrm/man/drm-memory.7 index c5167308f..98a5e9d69 100644 --- a/lib/libdrm/man/drm-memory.7 +++ b/lib/libdrm/man/drm-memory.7 @@ -1,5 +1,4 @@ -.\" automatically generated with -.\" docbook2mdoc drm-memory.xml > drm-memory.7 +.\" automatically generated with docbook2mdoc drm-memory.xml .Dd September 2012 .Dt DRM-MEMORY 7 .Os @@ -12,39 +11,50 @@ .Sh SYNOPSIS .Fd #include .Sh DESCRIPTION -Many modern high-end GPUs come with their own memory managers. They +Many modern high-end GPUs come with their own memory managers. +They even include several different caches that need to be synchronized -during access. Textures, framebuffers, command buffers and more need +during access. +Textures, framebuffers, command buffers and more need to be stored in memory that can be accessed quickly by the GPU. Therefore, memory management on GPUs is highly driver- and hardware-dependent. .Pp However, there are several frameworks in the kernel that are used by -more than one driver. These can be used for trivial mode-setting -without requiring driver-dependent code. But for +more than one driver. +These can be used for trivial mode-setting +without requiring driver-dependent code. +But for hardware-accelerated rendering you need to read the manual pages for the driver you want to work with. .Ss Dumb-Buffers Almost all in-kernel DRM hardware drivers support an API called .Em Dumb-Buffers . This API allows to create buffers -of arbitrary size that can be used for scanout. These buffers can be +of arbitrary size that can be used for scanout. +These buffers can be memory mapped via .Xr mmap 2 -so you can render into them on the CPU. However, GPU access to these -buffers is often not possible. Therefore, they are fine for simple +so you can render into them on the CPU. +However, GPU access to these +buffers is often not possible. +Therefore, they are fine for simple tasks but not suitable for complex compositions and renderings. .Pp The .Dv DRM_IOCTL_MODE_CREATE_DUMB ioctl can be -used to create a dumb buffer. The kernel will return a 32bit handle -that can be used to manage the buffer with the DRM API. You can +used to create a dumb buffer. +The kernel will return a 32bit handle +that can be used to manage the buffer with the DRM API. +You can create framebuffers with .Xr drmModeAddFB 3 -and use it for mode-setting and scanout. To access the buffer, you -first need to retrieve the offset of the buffer. The +and use it for mode-setting and scanout. +To access the buffer, you +first need to retrieve the offset of the buffer. +The .Dv DRM_IOCTL_MODE_MAP_DUMB ioctl requests the DRM subsystem to prepare the buffer for memory-mapping and returns a @@ -86,10 +96,13 @@ is the number of bits-per-pixel and must be a multiple of .Ql 8 . You most commonly want to pass .Ql 32 -here. The +here. +The .Fa flags -field is currently unused and must be zeroed. Different flags to -modify the behavior may be added in the future. After calling the +field is currently unused and must be zeroed. +Different flags to +modify the behavior may be added in the future. +After calling the ioctl, the .Fa handle , .Fa pitch @@ -97,16 +110,21 @@ and .Fa size fields are filled by the kernel. .Fa handle -is a 32bit gem handle that identifies the buffer. This is used by +is a 32bit gem handle that identifies the buffer. +This is used by several other calls that take a gem-handle or memory-buffer as -argument. The +argument. +The .Fa pitch field is the -pitch (or stride) of the new buffer. Most drivers use 32bit or 64bit -aligned stride-values. The +pitch (or stride) of the new buffer. +Most drivers use 32bit or 64bit +aligned stride-values. +The .Fa size field -contains the absolute size in bytes of the buffer. This can normally +contains the absolute size in bytes of the buffer. +This can normally also be computed with .Em (height * pitch + width) * bpp / 4 . .Pp @@ -114,7 +132,8 @@ To prepare the buffer for .Xr mmap 2 you need to use the .Dv DRM_IOCTL_MODE_MAP_DUMB -ioctl. It takes as argument a structure of type +ioctl. +It takes as argument a structure of type .Vt struct drm_mode_map_dumb : .Bd -literal struct drm_mode_map_dumb { @@ -128,10 +147,12 @@ You need to put the gem-handle that was previously retrieved via .Dv DRM_IOCTL_MODE_CREATE_DUMB into the .Fa handle -field. The +field. +The .Fa pad field is unused padding and must be -zeroed. After completion, the +zeroed. +After completion, the .Fa offset field will contain an offset that can be used with .Xr mmap 2 @@ -142,7 +163,8 @@ with .Dv DRM_IOCTL_MODE_DESTROY_DUMB . If you close the DRM file-descriptor, all open dumb-buffers are automatically -destroyed. This ioctl takes as argument a structure of type +destroyed. +This ioctl takes as argument a structure of type .Vt struct drm_mode_destroy_dumb : .Bd -literal struct drm_mode_destroy_dumb { @@ -152,16 +174,19 @@ struct drm_mode_destroy_dumb { .Pp You only need to put your handle into the .Fa handle -field. After this call, the handle +field. +After this call, the handle is invalid and may be reused for new buffers by the dumb-API. .Ss TTM .Em TTM stands for .Em Translation Table Manager and is a generic -memory-manager provided by the kernel. It does not provide a common +memory-manager provided by the kernel. +It does not provide a common user-space API so you need to look at each driver interface if you -want to use it. See for instance the radeon manpages for more +want to use it. +See for instance the radeon manpages for more information on memory-management with radeon and TTM. .Ss GEM .Em GEM @@ -169,55 +194,73 @@ stands for .Em Graphics Execution Manager and is a generic DRM memory-management framework in the kernel, that is used by many -different drivers. Gem is designed to manage graphics memory, +different drivers. +Gem is designed to manage graphics memory, control access to the graphics device execution context and handle -essentially NUMA environment unique to modern graphics hardware. Gem +essentially NUMA environment unique to modern graphics hardware. +Gem allows multiple applications to share graphics device resources -without the need to constantly reload the entire graphics card. Data +without the need to constantly reload the entire graphics card. +Data may be shared between multiple applications with gem ensuring that the correct memory synchronization occurs. .Pp Gem provides simple mechanisms to manage graphics data and control -execution flow within the linux DRM subsystem. However, gem is not a -complete framework that is fully driver independent. Instead, if +execution flow within the linux DRM subsystem. +However, gem is not a +complete framework that is fully driver independent. +Instead, if provides many functions that are shared between many drivers, but each driver has to implement most of memory-management with -driver-dependent ioctls. This manpage tries to describe the +driver-dependent ioctls. +This manpage tries to describe the semantics (and if it applies, the syntax) that is shared between all drivers that use gem. .Pp All GEM APIs are defined as .Xr ioctl 2 -on the DRM file descriptor. An application must be authorized via +on the DRM file descriptor. +An application must be authorized via .Xr drmAuthMagic 3 -to the current DRM-Master to access the GEM subsystem. A driver that +to the current DRM-Master to access the GEM subsystem. +A driver that does not support gem will return .Dv ENODEV for all -these ioctls. Invalid object handles return +these ioctls. +Invalid object handles return .Dv EINVAL and invalid object names return .Dv ENOENT . .Pp -Gem provides explicit memory management primitives. System pages are +Gem provides explicit memory management primitives. +System pages are allocated when the object is created, either as the fundamental storage for hardware where system memory is used by the graphics processor directly, or as backing store for graphics-processor resident memory. .Pp -Objects are referenced from user-space using handles. These are, for +Objects are referenced from user-space using handles. +These are, for all intents and purposes, equivalent to file descriptors but avoid -the overhead. Newer kernel drivers also support the +the overhead. +Newer kernel drivers also support the .Xr drm-prime 7 infrastructure which can return real file-descriptor for gem-handles -using the linux dma-buf API. Objects may be published with a name so -that other applications and processes can access them. The name -remains valid as long as the object exists. Gem-objects are -reference counted in the kernel. The object is only destroyed when +using the linux dma-buf API. +Objects may be published with a name so +that other applications and processes can access them. +The name +remains valid as long as the object exists. +Gem-objects are +reference counted in the kernel. +The object is only destroyed when all handles from user-space were closed. .Pp -Gem-buffers cannot be created with a generic API. Each driver -provides its own API to create gem-buffers. See for example +Gem-buffers cannot be created with a generic API. +Each driver +provides its own API to create gem-buffers. +See for example .Dv DRM_I915_GEM_CREATE , .Dv DRM_NOUVEAU_GEM_NEW or @@ -230,8 +273,10 @@ library from the .Em mesa3D distribution tries to provide a driver-independent API to create gbm buffers and retrieve a -gbm-handle to them. It allows to create buffers for different -use-cases including scanout, rendering, cursors and CPU-access. See +gbm-handle to them. +It allows to create buffers for different +use-cases including scanout, rendering, cursors and CPU-access. +See the libgbm library for more information or look at the driver-dependent man-pages (for example .Xr drm-intel 7 @@ -240,7 +285,8 @@ or .Pp Gem-buffers can be closed with the .Dv DRM_IOCTL_GEM_CLOSE -ioctl. It takes as argument +ioctl. +It takes as argument a structure of type .Vt struct drm_gem_close : .Bd -literal @@ -253,30 +299,37 @@ struct drm_gem_close { The .Fa handle field is the gem-handle to be -closed. The +closed. +The .Fa pad field is unused padding. -It must be zeroed. After this call the gem handle cannot be used by +It must be zeroed. +After this call the gem handle cannot be used by this process anymore and may be reused for new gem objects by the gem API. .Pp If you want to share gem-objects between different processes, you can create a name for them and pass this name to other processes -which can then open this gem-object. Names are currently 32bit -integer IDs and have no special protection. That is, if you put a +which can then open this gem-object. +Names are currently 32bit +integer IDs and have no special protection. +That is, if you put a name on your gem-object, every other client that has access to the DRM device and is authenticated via .Xr drmAuthMagic 3 to the current DRM-Master, can .Em guess the name -and open or access the gem-object. If you want more fine-grained +and open or access the gem-object. +If you want more fine-grained access control, you can use the new .Xr drm-prime 7 -API to retrieve file-descriptors for gem-handles. To create a name +API to retrieve file-descriptors for gem-handles. +To create a name for a gem-handle, you use the .Dv DRM_IOCTL_GEM_FLINK -ioctl. It takes as argument +ioctl. +It takes as argument a structure of type .Vt struct drm_gem_flink : .Bd -literal @@ -288,13 +341,16 @@ struct drm_gem_flink { .Pp You have to put your handle into the .Fa handle -field. After completion, the +field. +After completion, the kernel has put the new unique name into the .Fa name -field. You can now pass this name to +field. +You can now pass this name to other processes which can then import the name with the .Dv DRM_IOCTL_GEM_OPEN -ioctl. It takes as argument +ioctl. +It takes as argument a structure of type .Vt struct drm_gem_open : .Bd -literal @@ -308,37 +364,47 @@ struct drm_gem_open { You have to fill in the .Fa name field with -the name of the gem-object that you want to open. The kernel will +the name of the gem-object that you want to open. +The kernel will fill in the .Fa handle and .Fa size fields with the new handle and size -of the gem-object. You can now access the gem-object via the handle +of the gem-object. +You can now access the gem-object via the handle as if you created it with the gem API. .Pp Besides generic buffer management, the GEM API does not provide any -generic access. Each driver implements its own functionality on top -of this API. This includes execution-buffers, GTT management, -context creation, CPU access, GPU I/O and more. The next +generic access. +Each driver implements its own functionality on top +of this API. +This includes execution-buffers, GTT management, +context creation, CPU access, GPU I/O and more. +The next higher-level API is .Em OpenGL . So if you want to use more GPU features, you should use the .Em mesa3D library to create OpenGL contexts on DRM -devices. This does +devices. +This does .Em not require any windowing-system like X11, but can also be done on raw DRM devices. -However, this is beyond the scope of this man-page. You may have a -look at other mesa3D manpages, including libgbm and libEGL. 2D +However, this is beyond the scope of this man-page. +You may have a +look at other mesa3D manpages, including libgbm and libEGL. +2D software-rendering (rendering with the CPU) can be achieved with the dumb-buffer-API in a driver-independent fashion, however, for -hardware-accelerated 2D or 3D rendering you must use OpenGL. Any +hardware-accelerated 2D or 3D rendering you must use OpenGL. +Any other API that tries to abstract the driver-internals to access GEM-execution-buffers and other GPU internals, would simply reinvent -OpenGL so it is not provided. But if you need more detailed +OpenGL so it is not provided. +But if you need more detailed information for a specific driver, you may have a look into the driver-manpages, including .Xr drm-intel 7 , @@ -349,19 +415,24 @@ However, the .Xr drm-prime 7 infrastructure and the generic gem API as described here allow display-managers to handle graphics-buffers and render-clients -without any deeper knowledge of the GPU that is used. Moreover, it +without any deeper knowledge of the GPU that is used. +Moreover, it allows to move objects between GPUs and implement complex -display-servers that don't do any rendering on their own. See its +display-servers that don't do any rendering on their own. +See its man-page for more information. .Sh EXAMPLES This section includes examples for basic memory-management tasks. .Ss Dumb-Buffers This examples shows how to create a dumb-buffer via the generic -DRM API. This is driver-independent (as long as the driver +DRM API. +This is driver-independent (as long as the driver supports dumb-buffers) and provides memory-mapped buffers that can -be used for scanout. This example creates a full-HD 1920x1080 -buffer with 32 bits-per-pixel and a color-depth of 24 bits. The +be used for scanout. +This example creates a full-HD 1920x1080 +buffer with 32 bits-per-pixel and a color-depth of 24 bits. +The buffer is then bound to a framebuffer which can be used for scanout with the KMS API (see .Xr drm-kms 7 ) . diff --git a/lib/libdrm/man/drm.7 b/lib/libdrm/man/drm.7 index bd7769918..f7ab4d180 100644 --- a/lib/libdrm/man/drm.7 +++ b/lib/libdrm/man/drm.7 @@ -1,5 +1,4 @@ -.\" automatically generated with -.\" docbook2mdoc drm.xml > drm.7 +.\" automatically generated with docbook2mdoc drm.xml .Dd September 2012 .Dt DRM 7 .Os @@ -17,22 +16,27 @@ to manage (GPUs). It is designed to support the needs of complex graphics devices, usually containing programmable pipelines well suited to 3D graphics -acceleration. Furthermore, it is responsible for memory management, +acceleration. +Furthermore, it is responsible for memory management, interrupt handling and DMA to provide a uniform interface to applications. .Pp In earlier days, the kernel framework was solely used to provide raw hardware access to privileged user-space processes which implement -all the hardware abstraction layers. But more and more tasks were -moved into the kernel. All these interfaces are based on +all the hardware abstraction layers. +But more and more tasks were +moved into the kernel. +All these interfaces are based on .Xr ioctl 2 -commands on the DRM character device. The +commands on the DRM character device. +The .Em libdrm library provides wrappers for these system-calls and many helpers to simplify the API. .Pp When a GPU is detected, the DRM system loads a driver for the detected -hardware type. Each connected GPU is then presented to user-space via +hardware type. +Each connected GPU is then presented to user-space via a character-device that is usually available as .Pa /dev/drm0 and can be accessed with @@ -40,16 +44,20 @@ and can be accessed with and .Xr close 2 . However, it still depends on the graphics driver which interfaces are -available on these devices. If an interface is not available, the +available on these devices. +If an interface is not available, the syscalls will fail with .Ql EINVAL . .Ss Authentication -All DRM devices provide authentication mechanisms. Only a DRM-Master +All DRM devices provide authentication mechanisms. +Only a DRM-Master is allowed to perform mode-setting or modify core state and only one -user can be DRM-Master at a time. See +user can be DRM-Master at a time. +See .Xr drmSetMaster 3 for information on how to become DRM-Master and what the limitations -are. Other DRM users can be authenticated to the DRM-Master via +are. +Other DRM users can be authenticated to the DRM-Master via .Xr drmAuthMagic 3 so they can perform buffer allocations and rendering. .Ss Mode-Setting @@ -57,24 +65,32 @@ Managing connected monitors and displays and changing the current modes is called .Em Mode-Setting . This is -restricted to the current DRM-Master. Historically, this was +restricted to the current DRM-Master. +Historically, this was implemented in user-space, but new DRM drivers implement a kernel interface to perform mode-setting called .Em Kernel Mode Setting (KMS). If your hardware-driver supports it, you can use the KMS API provided by -DRM. This includes allocating framebuffers, selecting modes and -managing CRTCs and encoders. See +DRM. +This includes allocating framebuffers, selecting modes and +managing CRTCs and encoders. +See .Xr drm-kms 7 for more. .Ss Memory Management The most sophisticated tasks for GPUs today is managing memory -objects. Textures, framebuffers, command-buffers and all other kinds -of commands for the GPU have to be stored in memory. The DRM driver +objects. +Textures, framebuffers, command-buffers and all other kinds +of commands for the GPU have to be stored in memory. +The DRM driver takes care of managing all memory objects, flushing caches, -synchronizing access and providing CPU access to GPU memory. All -memory management is hardware driver dependent. However, two generic -frameworks are available that are used by most DRM drivers. These +synchronizing access and providing CPU access to GPU memory. +All +memory management is hardware driver dependent. +However, two generic +frameworks are available that are used by most DRM drivers. +These are the .Em Translation Table Manager (TTM) and the @@ -82,7 +98,8 @@ are the (GEM). They provide generic APIs to create, destroy and access buffers from user-space. However, there are still many differences between the drivers so -driver-depedent code is still needed. Many helpers are provided in +driver-depedent code is still needed. +Many helpers are provided in .Em libgbm (Graphics Buffer Manager) from the .Em mesa-project . diff --git a/lib/libdrm/man/drmAvailable.3 b/lib/libdrm/man/drmAvailable.3 index ae08cb91b..4f020fddb 100644 --- a/lib/libdrm/man/drmAvailable.3 +++ b/lib/libdrm/man/drmAvailable.3 @@ -1,5 +1,4 @@ -.\" automatically generated with -.\" docbook2mdoc drmAvailable.xml > drmAvailable.3 +.\" automatically generated with docbook2mdoc drmAvailable.xml .Dd September 2012 .Dt DRMAVAILABLE 3 .Os @@ -19,7 +18,8 @@ whether a kernel DRM driver is loaded. .Sh RETURN VALUE .Fn drmAvailable returns 1 if a DRM driver is -currently loaded. Otherwise 0 is returned. +currently loaded. +Otherwise 0 is returned. .Sh REPORTING BUGS Bugs in this function should be reported to https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm diff --git a/lib/libdrm/man/drmHandleEvent.3 b/lib/libdrm/man/drmHandleEvent.3 index da32723b7..5cd65ebf6 100644 --- a/lib/libdrm/man/drmHandleEvent.3 +++ b/lib/libdrm/man/drmHandleEvent.3 @@ -1,5 +1,4 @@ -.\" automatically generated with -.\" docbook2mdoc drmHandleEvent.xml > drmHandleEvent.3 +.\" automatically generated with docbook2mdoc drmHandleEvent.xml .Dd September 2012 .Dt DRMHANDLEEVENT 3 .Os diff --git a/lib/libdrm/man/drmModeGetResources.3 b/lib/libdrm/man/drmModeGetResources.3 index 03a74956c..ef2a7ef4a 100644 --- a/lib/libdrm/man/drmModeGetResources.3 +++ b/lib/libdrm/man/drmModeGetResources.3 @@ -1,5 +1,4 @@ -.\" automatically generated with -.\" docbook2mdoc drmModeGetResources.xml > drmModeGetResources.3 +.\" automatically generated with docbook2mdoc drmModeGetResources.xml .Dd September 2012 .Dt DRMMODEGETRESOURCES 3 .Os @@ -19,7 +18,8 @@ allocates, populates, and returns a .Vt drmModeRes structure containing -information about the current display configuration. The structure +information about the current display configuration. +The structure contains the following fields: .Bd -literal typedef struct _drmModeRes { @@ -49,9 +49,11 @@ The and .Fa crtcs fields list the available CRTCs in -the configuration. A CRTC is simply an object that can scan out a +the configuration. +A CRTC is simply an object that can scan out a framebuffer to a display sink, and contains mode timing and relative -position information. CRTCs drive encoders, which are responsible for +position information. +CRTCs drive encoders, which are responsible for converting the pixel stream into a specific display protocol (e.g., MIPI or HDMI). .Pp @@ -60,7 +62,8 @@ The and .Fa connectors fields list the available -physical connectors on the system. Note that some of these may not be +physical connectors on the system. +Note that some of these may not be exposed from the chassis (e.g., LVDS or eDP). Connectors are attached to encoders and contain information about the attached display sink (e.g., width and height in mm, subpixel ordering, and various other @@ -71,7 +74,8 @@ The and .Fa encoders fields list the available encoders -on the device. Each encoder may be associated with a CRTC, and may be +on the device. +Each encoder may be associated with a CRTC, and may be used to drive a particular encoder. .Pp The @@ -85,7 +89,8 @@ framebuffer for this device (i.e., the scanout size limit). returns a drmModeRes structure pointer on success, .Ql NULL -on failure. The +on failure. +The returned structure must be freed with .Xr drmModeFreeResources 3 . .Sh REPORTING BUGS