simplify Makefiles for use with docbook2mdoc-1.1.0
and regen for improved formatting: correct linebreaks in literal displays; and new sentence, new line
This commit is contained in:
schwarze
parent
90885b2752
commit
05166be26d
@ -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 <bsd.xorg.mk>
|
||||
|
||||
@ -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
|
||||
<match target="font">
|
||||
@ -142,7 +148,8 @@ Anti-aliasing can be disabled for all fonts by the following incantation:
|
||||
</match>
|
||||
.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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 <xf86drmMode.h>
|
||||
.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
|
||||
|
||||
@ -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 <xf86drm.h>
|
||||
.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 ) .
|
||||
|
||||
@ -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 .
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user