---
title: Chapter 5. The X Window System
part: Part I. Getting Started
prev: books/handbook/ports
next: books/handbook/wayland
description: This chapter describes how to install and configure the X Window System providing a graphical environment
tags: ["AMD", "DRM", "Fonts", "Graphics", "Input", "Intel", "Monitor", "NVIDIA", "PRIME", "SCFB", "TrueType", "VESA", "Video", "X11", "Xf86", "Xorg"]
showBookMenu: true
weight: 7
params:
  path: "/books/handbook/x11/"
---

[[x11]]
= The X Window System
:doctype: book
:toc: macro
:toclevels: 2
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 5
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/handbook/x11/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

[[x11-synopsis]]
== Synopsis

An crossref:bsdinstall[bsdinstall-synopsis,installation]
of FreeBSD using man:bsdinstall[8]
does not automatically install a graphical user interface.
This chapter describes how to install and configure
the man:Xorg[1] server, which provides the open source X Window System
(colloquially X11) used to provide a graphical environment.

Before reading this chapter:

* Know how to install additional third-party software as described
in crossref:ports[ports,Installing Applications: Packages and Ports].

Read this chapter to learn:

* How to select and install drivers for the graphics processor (GPU).
* The various components of the X Window System,
and how they interoperate.
* How to install and configure the X.org server.
* How to install fonts for the X Window System.

[[x-graphic-card-drivers]]
== Graphics Drivers

_**abstract**: Identify the GPU, the port providing a driver for it,
install it, then enable it to run at subsequent boot with man:sysrc[8]._

Before FreeBSD can render a graphical environment,
it needs a kernel module to drive the graphics processor.
Graphics drivers are a fast-moving, cross-platform target,
which is why this is developed and distributed
separately from the FreeBSD base system.

The following table shows the different graphics processors
supported by FreeBSD, their corresponding module,
and which port provides it:

.Supported Graphics Devices
[options="header", cols="1,1,1,1"]
|===
| Type | License | Module | Port

| Intel(R)
| Open Source
| `i915kms`
| package:graphics/drm-kmod[]

| AMD(R)
| Open Source
| `amdgpu` or `radeonkms`
| package:graphics/drm-kmod[]

| NVIDIA(R)
| Proprietary
| `nvidia-drm`, `nvidia-modeset`, or `nvidia`
| package:graphics/nvidia-drm-kmod[] or +
package:x11/nvidia-driver[]

| System Console Framebuffer
| Open Source
| `scfb`
| package:x11-drivers/xf86-video-scfb[]

| VESA BIOS Extension
| Open Source
| `vesa`
| package:x11-drivers/xf86-video-vesa[]

| VirtualBox(R)
| Open Source
| `vboxvideo`
| package:emulators/virtualbox-ose-additions[]

| VMware(R)
| Open Source
| `vmwgfx`
| package:x11-drivers/xf86-video-vmware[]
|===

There are several generations of driver technologies supported.

* Direct Rendering drivers allowing PRIME offloading.
PRIME allows for multiple providers of graphics processing to coexist.
PRIME is described further in <<x-config-gpu>>.

* Kernel Modesetting (crossref:glossary[kms-glossary,KMS])
This allows the driver to directly specify the display mode.
This is required to support suspend and resume when using the man:vt[4]
console driver.

* User Modesetting
The oldest class of drivers is still supported, however they
may only be used with man:sc[4] console and older versions of the
man:Xorg[1] graphical environment.

The following command can be used to identify
which graphics processor is installed in the system:

[source,shell]
....
% pciconf -lv | grep -B3 display
....

The output should be similar to the following:

[.programlisting]
....
vgapci1@pci0:0:2:0:     class=0x030000 rev=0x0c hdr=0x00 vendor=0x8086 device=0x46a6 subvendor=0x1028 subdevice=0x0b29
    vendor     = 'Intel Corporation'
    device     = 'Alder Lake-P GT2 [Iris Xe Graphics]'
    class      = display
....

Detailed instructions on installing and enabling these drivers
are in the subsequent subsections.

[WARNING]
====
If the graphics processor is not supported by Intel(R), AMD(R),
or NVIDIA(R) drivers, then SCFB or VESA modules should be used.
SCFB module must be used when booting in UEFI mode.
VESA module must be used when booting in BIOS mode.

This command can be used to check the booting mode:

[source,shell]
....
% sysctl machdep.bootmethod
....

The output should be similar to the following:

[.programlisting]
....
machdep.bootmethod: UEFI
....
====

[[x-configuration-intel]]
=== Intel(R) Graphics

The package:graphics/drm-kmod[] package indirectly provides
a range of kernel modules for use with Intel(R) Graphics.
Recent versions of these modules can be used in conjunction
with other graphics processors in PRIME with no special configuration.

The Intel(R) Graphics driver can be installed
by executing the following command:

[source,shell]
....
# pkg install drm-kmod
....

Then add the module to [.filename]#/etc/rc.conf# file,
by executing the following command:

[source,shell]
....
# sysrc kld_list+=i915kms
....

[[x-configuration-amd]]
=== AMD(R) Graphics

The package:graphics/drm-kmod[] package indirectly provides
kernel modules for a range of AMD(R) Graphics processors.
The modules `amdgpu` or `radeonkms` can be used
depending the generation of the hardware.
The FreeBSD project maintains a link:https://wiki.freebsd.org/Graphics/AMD-GPU-Matrix[AMD graphics support matrix]
showing support levels and to determine which driver must be used.

The AMD(R) Graphics drivers can be installed
by executing the following command:

[source,shell]
....
# pkg install drm-kmod
....

Enable the current module by adding it to the [.filename]#/etc/rc.conf#
file, executing the following command:

[source,shell]
....
# sysrc kld_list+=amdgpu
....

For older graphics (pre-HD7000/Tahiti),
instead enable the legacy module by adding it to the
[.filename]#/etc/rc.conf# file, executing the following command:

[source,shell]
....
# sysrc kld_list+=radeonkms
....

[[x-configuration-nvidia]]
=== NVIDIA(R) Graphics

NVIDIA(R) produces standalone or discrete graphics processors,
and provides a proprietary driver for FreeBSD.
The FreeBSD Ports Collection provides over a decade of drivers
for supporting generations of NVIDIA graphics.

Administrators should install the latest driver
supported by their hardware.

The following table shows the port containing the driver,
the kernel module recommended for loading,
and a link to the list of hardware supported by that driver:

.Supported versions of NVIDIA(R) Graphics drivers
[options="header", cols="1,1,1"]
|===
| Port | Module | Supported hardware

| package:graphics/nvidia-drm-kmod[]
| `nvidia-drm` or +
`nvidia-modeset`
| link:https://www.nvidia.com/Download/driverResults.aspx/210651/en-us/[supported hardware]

| package:x11/nvidia-driver-470[]
| `nvidia-modeset`
| link:https://www.nvidia.com/Download/driverResults.aspx/194639/en-us/[supported hardware]

| package:x11/nvidia-driver-390[] or +
package:x11/nvidia-secondary-driver-390[]
| `nvidia-modeset`
| link:https://www.nvidia.com/Download/driverResults.aspx/191122/en-us/[supported hardware]

| package:x11/nvidia-driver-340[]
| `nvidia`
| link:https://www.nvidia.com/Download/driverResults.aspx/156167/en-us/[supported hardware]

| package:x11/nvidia-driver-304[]
| `nvidia`
| link:https://www.nvidia.com/Download/driverResults.aspx/123712/en-us/[supported hardware]

|===

The latest NVIDIA(R) Graphics driver can be installed
by running the following command:

[source,shell]
....
# pkg install nvidia-drm-kmod
....

To enable the driver, add the module to
[.filename]#/etc/rc.conf# file, by executing the following command:

[source,shell]
....
# sysrc kld_list+=nvidia-drm
....

This is the direct rendering crossref:glossary[kms-glossary,KMS] driver.

Kernel modesetting is the option to set the graphics mode in the kernel.
Enable it for subsequent boots with the following man:loader.conf[5]
tunable:

[source,shell]
....
hw.nvidiadrm.modeset="1"
....

Both PRIME and crossref:wayland[wayland-synopsis,Wayland]
require kernel modesetting.

Prior versions of the driver do not support Direct Rendering.
Instead use the modesetting module,
by executing the following command:
[source,shell]
....
# sysrc kld_list+=nvidia-modeset
....

If requiring Nvidia drivers prior to 390,
note that they do not support kernel modesetting,
and thus they must be used with the legacy man:sc[4] console driver,
and a package:x11/xorg-server[] version prior to 1.20.

Enable them in [.filename]#/etc/rc.conf# with the following command:

[source,shell]
....
# sysrc kld_list+=nvidia
....

[[firmware]]
Some graphic cards will need special firmware that needs to be downloaded for
the device to work properly.
The man:fwget[8] utility can download and install the necessary files under
[.filename]#/boot/firmware#.
man:fwget[8] will scan the 'PCI' devices and download the firmware for those
devices that need it.

[[x-overview]]
== X Window System Overview

The X Window System is the heritage
graphical stack for UNIX(R) platforms,
supporting the latest technologies
while maintaining support for generations of applications.
Applications, including the components of the desktop,
are hosted by the man:Xorg[1] server.
This system is network aware and its various components
can interoperate across networks.

[[x-install]]
== Installing The X.org Server

_**abstract**: The package:x11/xorg[X.org] server
must be installed to host the crossref:desktop[desktop-synopsis,desktop].
Users must be added to the `video` group to use it._

Once a graphics driver is installed and enabled,
the X.org server can be installed as a meta-package,
or compiled locally with the ports tree.

The full meta-package can be installed quickly
but with fewer options for customization:

[source,shell]
....
# pkg install xorg
....

This installation results in the complete X Window System
being installed, including a traditional window manager, man:twm[1],
and surrounding traditional desktop suite.
Most users will want to install and configure a
contemporary crossref:desktop[desktop-synopsis,desktop] of their choice.

The current user must be a member of the `video` group
to run a graphical environment.
To add a user to the `video` group, execute the following command:

[source,shell]
....
# pw groupmod video -m username
....

To run the X Window System, use man:startx[1] from package:x11/xinit[],
or install and configure a display manager
to start a graphical login on boot.

[TIP]
====
A smaller version of the X Window System suitable for experienced users
is available in package:x11/xorg-minimal[].
Most of the documents, libraries, and applications will not be installed.
Some applications require these additional components to function.
====

[[x-config]]
== X.org Configuration

_**abstract**: If the defaults for the monitor or input devices,
are not satisfactory,
crossref:desktop[desktop-synopsis,desktops]
include GUIs for configuring them, or they can be configured manually._

The X.org server supports most common graphics processors, monitors,
and input devices.
First, try the defaults.
This subsection provides an overview of their configuration.

[[x-config-files]]
=== X.org Configuration Files

Historically, the X.org server was configured with files in
[.filename]#/usr/local/etc/X11/#.
This is still supported for edge cases,
but conflicts with dynamic autoconfiguration.

Do not create configuration for the X.org server in
[.filename]#xorg.conf#
or run `Xorg -configure` unless automatic configuration fails.

X.org server looks in several directories for configuration files.
[.filename]#/usr/local/etc/X11/# is the *recommended* directory
for these files on FreeBSD.
Using this directory helps keep application files separate from
operating system files.

It is easier to use multiple files that each configure a
specific setting than the traditional single [.filename]#xorg.conf#.
These files are stored in the
[.filename]#/usr/local/etc/X11/xorg.conf.d/# subdirectory.

[[x-config-gpu]]
=== Graphics Configuration

Direct rendering provides the ability to seamlessly
use a discrete graphics processor (dGPU) alongside
an integrated graphics processor (iGPU), called PRIME.
The drivers will automatically offload intensive tasks to the dGPU
when required, and power it down when able.

To launch applications on the more powerful GPU in PRIME,
use the `DRI_PRIME=1` environment variable.

If multiple graphics drivers are conflicting,
the driver for the graphics processor can be specified in the
[.filename]#/usr/local/etc/X11/xorg.conf.d/# directory.

To configure the Intel(R) driver in a configuration file:

[[x-config-video-cards-file-intel]]
.Select Intel(R) Graphics Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/20-intel.conf#

[.programlisting]
....
Section "Device"
	Identifier "Card0"
	Driver     "intel"
EndSection
....
====

To configure the AMD(R) driver in a configuration file:

[[x-config-video-cards-file-amd]]
.Select AMD(R) Graphics Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/20-radeon.conf#

[.programlisting]
....
Section "Device"
	Identifier "Card0"
	Driver     "radeon"
EndSection
....
====

To configure the NVIDIA(R) driver in a configuration file:

[[x-config-video-cards-file-nvidia]]
.Select NVIDIA(R) Graphics Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/20-nvidia.conf#

[.programlisting]
....
Section "Device"
	Identifier "Card0"
	Driver     "nvidia"
EndSection
....
====

[TIP]
====
package:x11/nvidia-xconfig[] can also be used to perform basic control
over configuration options available in the NVIDIA driver.
====

To configure the SCFB driver in a configuration file:

[[x-config-video-cards-file-sfcb]]
.Select SCFB Graphics Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/20-scfb.conf#

[.programlisting]
....
Section "Device"
	Identifier "Card0"
	Driver     "scfb"
EndSection
....
====

To configure the VESA driver in a configuration file:

[[x-config-video-cards-file-vesa]]
.Select VESA Graphics Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/20-vesa.conf#

[.programlisting]
....
Section "Device"
	Identifier "Card0"
	Driver     "vesa"
EndSection
....
====

To configure multiple graphics processors, the `BusID` can be added.
A list of graphics processor bus ``ID``s can be displayed by executing:

[source,shell]
....
% pciconf -lv | grep -B3 display
....

The output should be similar to the following:

[.programlisting]
....
vgapci0@pci0:0:2:0:     class=0x030000 rev=0x0c hdr=0x00 vendor=0x8086 device=0x46a6 subvendor=0x1028 subdevice=0x0b29
    vendor     = 'Intel Corporation'
    device     = 'Alder Lake-P GT2 [Iris Xe Graphics]'
    class      = display
--
vgapci0@pci0:1:0:0:     class=0x030200 rev=0xa1 hdr=0x00 vendor=0x10de device=0x25b9 subvendor=0x1028 subdevice=0x0b29
    vendor     = 'NVIDIA Corporation'
    device     = 'GA107GLM [RTX A1000 Laptop GPU]'
    class      = display
....

[[x-config-video-cards-file-multiple]]
.Select Intel(R) Graphics Driver and NVIDIA(R) Graphics Driver in a File
[example]
====

[.filename]#/usr/local/etc/X11/xorg.conf.d/20-drivers.conf#

[.programlisting]
....
Section "Device"
	Identifier "Card0"
	Driver     "intel"
	BusID     "pci0:0:2:0"
EndSection

Section "Device"
	Identifier "Card1"
	Driver     "nvidia"
	BusID     "pci0:0:2:1"
EndSection
....
====

[[x-config-monitors]]
=== Monitor Configuration

Almost all monitors support the Extended Display Identification Data
standard (`EDID`).
X.org uses `EDID` to communicate with the monitor
and detect the supported resolutions and refresh rates.
Then it selects the most appropriate combination of settings
to use with that monitor.

Other resolutions supported by the monitor can be selected atomically
after the X server has been started with man:xrandr[1],
or in the X.org server configuration files.

[[x-config-monitors-xrandr]]
==== Using RandR (Resize and Rotate)

Run man:xrandr[1] in an X session without any parameters
to see a list of video outputs and detected monitor modes:

[source,shell]
....
% xrandr
....

The output should be similar to the following:

[.programlisting]
....
Screen 0: minimum 320 x 200, current 2560 x 960, maximum 8192 x 8192
LVDS-1 connected 1280x800+0+0 (normal left inverted right x axis y axis) 261mm x 163mm
   1280x800      59.99*+  59.81    59.91    50.00  
   1280x720      59.86    59.74  
   1024x768      60.00  
   1024x576      59.90    59.82  
   960x540       59.63    59.82  
   800x600       60.32    56.25  
   864x486       59.92    59.57  
   640x480       59.94  
   720x405       59.51    58.99  
   640x360       59.84    59.32  
VGA-1 connected primary 1280x960+1280+0 (normal left inverted right x axis y axis) 410mm x 257mm
   1280x1024     75.02    60.02  
   1440x900      74.98    60.07  
   1280x960      60.00* 
   1280x800      74.93    59.81  
   1152x864      75.00  
   1024x768      75.03    70.07    60.00  
   832x624       74.55  
   800x600       72.19    75.00    60.32    56.25  
   640x480       75.00    72.81    66.67    59.94  
   720x400       70.08  
HDMI-1 disconnected (normal left inverted right x axis y axis)
DP-1 disconnected (normal left inverted right x axis y axis)
HDMI-2 disconnected (normal left inverted right x axis y axis)
DP-2 disconnected (normal left inverted right x axis y axis)
DP-3 disconnected (normal left inverted right x axis y axis)
....

This shows that the `VGA-1` output is being used to display
a screen resolution of 1280x960 pixels at a refresh rate of about 60 Hz.
The `LVDS-1` is being used as a secondary monitor to display
a screen resolution of 1280x800 pixels at a refresh rate of about 60 Hz.
Monitors are not attached to the `HDMI-1`, `HDMI-2`, `DP-1`, `DP-2`, and
`DP-3` connectors.

Any of the other display modes can be selected with man:xrandr[1].
For example, to switch to 1280x1024 at 60 Hz:

[source,shell]
....
% xrandr --output LVDS-1 --mode 1280x720 --rate 60
....

[TIP]
====
Oftentimes, a black screen upon starting X can be fixed
by adding an `xrandr --auto` step to the initialization process.
====

[[x-config-monitors-file]]
==== Using the X.org Configuration Files

The monitor configuration can also be set in a configuration file.

To set a screen resolution of 1024x768 in a configuration file:

.Set Screen Resolution in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/10-monitor.conf#

[.programlisting]
....
Section "Screen"
	Identifier "Screen0"
	Device     "Card0"
	SubSection "Display"
	Modes      "1024x768"
	EndSubSection
EndSection
....
====

[[x-config-input]]
=== Input Configuration

The package:Xorg[X.org] server provides the package:x11/libinput[]
library, a cross-platform effort to support all touch, pointing,
and keyboard devices under a unified library.
Unless specified otherwise, this is loaded automatically.

Individual device settings for man:libinput[4] can be tuned in the
crossref:desktop[desktop-synopsis,desktop's] GUI,
or manually with package:x11/xinput[xinput]
and package:x11/setxkbmap[setxkbmap].

Alternatively, there are older, lightweight, individual drivers for
specific input devices available in the package:x11-drivers[] category
named x11/xf86-input-[foo].
This approach requires manual configuration of the X.org server.
Both are described in this subsection.

[[x-config-input-atmoic]]
==== Using Atomic Input Configuration

Devices supported by man:libinput[4] can be configured
with graphical utilities included with the
crossref:desktop[desktop-synopsis,desktop] of choice,
or manually and atomically at runtime with package:x11/xinput[]
and package:x11/setxkbmap[].

To ask man:libinput[4] what devices it's currently attached to,
run man:xinput[1] with no arguments:

[source,shell]
....
$ xinput
....

Its output should be similar to the following:

[example]
....

⎡ Virtual core pointer                    	id=2	[master pointer  (3)]
⎜   ↳ Virtual core XTEST pointer              	id=4	[slave  pointer  (2)]
⎜   ↳ System mouse                            	id=7	[slave  pointer  (2)]
⎜   ↳ VEN_0488:00 0488:1031 Mouse             	id=11	[slave  pointer  (2)]
⎜   ↳ VEN_0488:00 0488:1031 TouchPad          	id=12	[slave  pointer  (2)]
⎣ Virtual core keyboard                   	id=3	[master keyboard (2)]
    ↳ Virtual core XTEST keyboard             	id=5	[slave  keyboard (3)]
    ↳ System keyboard multiplexer             	id=6	[slave  keyboard (3)]
    ↳ Power Button                            	id=8	[slave  keyboard (3)]
    ↳ Sleep Button                            	id=9	[slave  keyboard (3)]
    ↳ AT keyboard                             	id=10	[slave  keyboard (3)]
....

All settings supported by these devices are provided as properties,
which can be listed and set atomically.
Pointing devices have many configurable properties, keyboards usually need none.

To customize the keyboard, take a look at man:setxkbmap[1].

Once satisfied with the configuration, simply add the lines to the
X initialization script such as [.filename]#~/.Xsession# or [.filename]#~/.xinitrc#.

[[x-config-input-file]]
==== Using X.org Configuration Files


[TIP]
====
Some desktop environments (such as crossref:desktop[kde-environment,KDE Plasma]) provide a graphical UI for setting these parameters.
Check if this is the case before resorting to manual configuration editing.
====

[[x-config-input-keyboard-layout]]
For example, to manually configure the X.org server for the keyboard layout:

.Setting a Keyboard Layout
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/00-keyboard.conf#

[.programlisting]
....
Section "InputClass"
        Identifier "Keyboard1"
        MatchIsKeyboard "on"
        Option "XkbLayout" "es, fr"
        Option "XkbModel" "pc104"
        Option "XkbVariant" ",qwerty"
        Option "XkbOptions" "grp:win_space_toggle"
EndSection
....
====

[[x-fonts]]
== Using Fonts in the X Window System

_**abstract**: Additional fonts can be installed from the
package:x11-fonts[] category or placed in [.filename]#~/.fonts#.
They are available immediately to modern applications.
Configuration for older applications is available and described as well._

The X Window System provides the X FreeType interface library
(man:Xft[3]) to render vector or outline fonts,
as well as the traditional X Logical Font Description system
maintaining compatibility with generations of applications and fonts.

There are primarily two types of fonts users will be interested in:

* OpenType fonts or TrueType(R) fonts are for displaying on a screen.
* Adobe(R) PostScript(R) Type 1 fonts are for printing to paper.

These are both vector or outline fonts, there are also bitmap fonts.

The FreeBSD Ports Collection includes a wide and growing catalog
of free, high quality fonts available for installation
in the package:x11-fonts[] category.

System-wide font packages installed from the ports collection
live in `[.filename]#/usr/local/share/fonts/#`.
Fonts for a single user can be placed in `[.filename]#~/.fonts/#`,
or `[.filename]#~/.local/share/fonts/#`.

Fonts in either directory or subdirectories will be available
for immediate use when the font information cache is rebuilt.
To trigger this manually, issue:

[source,shell]
....
% fc-cache
....

Plenty of free, high quality fonts of both types are available in the
ports tree which can be readily used with X Window System.
This chapter provides a brief overview of both,
as well as configuring the X FreeType interface.

For more information about how to install and configure fonts on FreeBSD,
please read the article link:{fonts}[Fonts and FreeBSD].

[[truetype]]
=== TrueType(R) Fonts

X.org has built in support for rendering TrueType(R) fonts.
There are two different modules that can enable this functionality.
The freetype module is used in this example because it is more consistent with the other font rendering back-ends.
To enable the freetype module just add the following line to the `"Module"` section of [.filename]#/usr/local/etc/X11/xorg.conf.d/90-fonts.conf#.

[.programlisting]
....
Load  "freetype"
....

Now make a directory for the TrueType(R) fonts (for example, [.filename]#/usr/local/share/fonts/TrueType#) and copy all of the TrueType(R) fonts into this directory.
Keep in mind that TrueType(R) fonts cannot be directly taken from an Apple(R) Mac(R); they must be in UNIX(R)/MS-DOS(R)/Windows(R) format for use by X.org.
Once the files have been copied into this directory, use mkfontscale to create a [.filename]#fonts.dir#, so that the X font renderer knows that these new files have been installed.
`mkfontscale` can be installed as a package:

[source,shell]
....
# pkg install mkfontscale
....

Then create an index of X font files in a directory:

[source,shell]
....
# cd /usr/local/share/fonts/TrueType
# mkfontscale
....

Now add the TrueType(R) directory to the font path.
This is just the same as described in <<type1>>:

[source,shell]
....
% xset fp+ /usr/local/share/fonts/TrueType
% xset fp rehash
....

or add a `FontPath` line to [.filename]#xorg.conf#.

Now Gimp, LibreOffice, and all of the other X applications should now recognize the installed TrueType(R) fonts.
Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within LibreOffice) will look much better now.

[[type1]]
=== Type1 Fonts

The URW font collection (package:x11-fonts/urwfonts[]) includes high quality versions of standard type1 fonts (Times Roman(TM), Helvetica(TM), Palatino(TM) and others).
The Freefonts collection (package:x11-fonts/freefonts[]) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts.

To install the above Type1 font collections from binary packages, run the following commands:

[source,shell]
....
# pkg install urwfonts
....

And likewise with the freefont or other collections.
To have a manually configured X server detect these fonts, add an appropriate line to the X server configuration file ([.filename]#/usr/local/etc/X11/xorg.conf.d/90-fonts.conf#), which reads:

[.programlisting]
....
Section "Files"
  FontPath "/usr/local/share/fonts/urwfonts/"
EndSection
....

Alternatively, at the command line in the X session run:

[source,shell]
....
% xset fp+ /usr/local/share/fonts/urwfonts
% xset fp rehash
....

This will work but will be lost when the X session is closed, unless it is added to the startup file ([.filename]#~/.xinitrc# for a normal `startx` session, or [.filename]#~/.xsession# when logging in through a graphical login manager like XDM).
A third way is to use the new [.filename]#/usr/local/etc/fonts/local.conf# as demonstrated in <<antialias>>.

[[antialias]]
=== Anti-Aliased Fonts

All fonts in X.org that are found in [.filename]#/usr/local/share/fonts/# and [.filename]#~/.fonts/# are automatically made available for anti-aliasing to Xft-aware applications.
Most recent applications are Xft-aware, including KDE, GNOME, and Firefox.

To control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file [.filename]#/usr/local/etc/fonts/local.conf#.
Several advanced features of the Xft font system can be tuned using this file; this section describes only some simple possibilities.
For more details, please see man:fonts-conf[5].

This file must be in XML format.
Pay careful attention to case, and make sure all tags are properly closed.
The file begins with the usual XML header followed by a DOCTYPE definition, and then the `<fontconfig>` tag:

[.programlisting]
....
<?xml version="1.0"?>
      <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
      <fontconfig>
....

As previously stated, all fonts in [.filename]#/usr/local/share/fonts/# as well as [.filename]#~/.fonts/# are already made available to Xft-aware applications.
To add another directory outside of these two directory trees, add a line like this to [.filename]#/usr/local/etc/fonts/local.conf#:

[.programlisting]
....
<dir>/path/to/my/fonts</dir>
....

After adding new fonts, and especially new font directories, rebuild the font caches:

[source,shell]
....
# fc-cache -f
....

Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes "staircases" from large text, but can cause eyestrain if applied to normal text.
To exclude font sizes smaller than 14 point from anti-aliasing, include these lines:

[.programlisting]
....
	<match target="font">
	    <test name="size" compare="less">
		<double>14</double>
	    </test>
	    <edit name="antialias" mode="assign">
		<bool>false</bool>
	    </edit>
	</match>
	<match target="font">
	    <test name="pixelsize" compare="less" qual="any">
		<double>14</double>
	    </test>
	    <edit mode="assign" name="antialias">
		<bool>false</bool>
	    </edit>
	</match>
....

Spacing for some monospaced fonts might also be inappropriate with anti-aliasing.
This seems to be an issue with KDE, in particular.
One possible fix is to force the spacing for such fonts to be 100.
Add these lines:

[.programlisting]
....
	<match target="pattern" name="family">
	   <test qual="any" name="family">
	       <string>fixed</string>
	   </test>
	   <edit name="family" mode="assign">
	       <string>mono</string>
	   </edit>
	</match>
	<match target="pattern" name="family">
	    <test qual="any" name="family">
		<string>console</string>
	    </test>
	    <edit name="family" mode="assign">
		<string>mono</string>
	    </edit>
	</match>
....

(this aliases the other common names for fixed fonts as `"mono"`), and then add:

[.programlisting]
....
	<match target="pattern" name="family">
	     <test qual="any" name="family">
		 <string>mono</string>
	     </test>
	     <edit name="spacing" mode="assign">
		 <int>100</int>
	     </edit>
	 </match>
....

Certain fonts, such as Helvetica, may have a problem when anti-aliased.
Usually this manifests itself as a font that seems cut in half vertically.
At worst, it may cause applications to crash.
To avoid this, consider adding the following to [.filename]#local.conf#:

[.programlisting]
....
	<match target="pattern" name="family">
	     <test qual="any" name="family">
		 <string>Helvetica</string>
	     </test>
	     <edit name="family" mode="assign">
		 <string>sans-serif</string>
	     </edit>
	 </match>
....

After editing [.filename]#local.conf#, make certain to end the file with the `</fontconfig>` tag.
Not doing this will cause changes to be ignored.

Users can add personalized settings by creating their own [.filename]#~/.config/fontconfig/fonts.conf#.
This file uses the same `XML` format described above.

One last point: with an LCD screen, sub-pixel sampling may be desired.
This basically treats the (horizontally separated) red, green and blue components separately to improve the horizontal resolution; the results can be dramatic.
To enable this, add the line somewhere in [.filename]#local.conf#:

[.programlisting]
....
	 <match target="font">
	     <test qual="all" name="rgba">
		 <const>unknown</const>
	     </test>
	     <edit name="rgba" mode="assign">
		 <const>rgb</const>
	     </edit>
	 </match>
....

[NOTE]
====
Depending on the sort of display, `rgb` may need to be changed to `bgr`, `vrgb` or `vbgr`: experiment and see which works best.
====
