Chapter 14. Support for the X Resize and Rotate Extension
Prev | Part I. Installation and Configuration Instructions | Next

## Chapter 14. Support for the X Resize and Rotate Extension

This NVIDIA driver release contains support for the X Resize and Rotate (RandR) Extension versions 1.1, 1.2, and 1.3. The version of the RandR extension advertised to X clients is controlled by the X server: the RandR extension and protocol are provided by the X server, which routes protocol requests to the NVIDIA X driver. Run `xrandr --version` to check the version of RandR provided by the X server.

## RandR Support

Specific supported features include:

- Modes can be set per-screen, and the X screen can be resized through the RRSetScreenConfig request (e.g., with xrandr(1)'s '--size' and '--rate' command line options).

- The X screen can be resized with the RandR 1.2 RRSetScreenSize request (e.g., with xrandr(1)'s '--fb' command line option).

- The state of the display hardware can be queried with the RandR 1.2 and 1.3 RRGetScreenResources, RRGetScreenResourcesCurrent, RRGetOutputInfo, and RRGetCrtcInfo requests (e.g., with xrandr(1)'s '--query' command line option).

- Modes can be set with RandR CRTC granularity with the RandR 1.2 RRSetCrtcConfig request. E.g., `xrandr --output DVI-I-2 --mode 1920x1200`.

- Rotation can be set with RandR CRTC granularity with the RandR 1.2 RRSetCrtcConfig request. E.g., `xrandr --output DVI-I-2 --mode 1920x1200 --rotation left`.

- Per-CRTC transformations can be manipulated with the RandR 1.3 RRSetCrtcTransform and RRGetCrtcTransform requests. E.g., `xrandr --output DVI-I-3 --mode 1920x1200 --transform 43.864288330078125,21.333328247070312,-16384,0,43.864288330078125,0,0,0.0321197509765625,19.190628051757812`.

- The RandR 1.0/1.1 requests RRGetScreenInfo and RRSetScreenConfig manipulate MetaModes. The MetaModes that the X driver uses (either user-requested or implicitly generated) are reported through the RRGetScreenInfo request (e.g., `xrandr --query --q1`) and chosen through the RRSetScreenConfig request (e.g., `xrandr --size 1920x1200 --orientation left`).

The configurability exposed through RandR is also available through the MetaMode syntax, independent of X server version. See MetaModes for more details. As an example, these two commands are equivalent:

      xrandr --output DVI-I-2 --mode 1280x1024 --pos 0x0 --rotate left \
        --output DVI-I-3 --mode 1920x1200 --pos 0x0

      nvidia-settings --assign CurrentMetaMode="DVI-I-2: 1280x1024 +0+0 \
        { Rotation=left }, DVI-I-3: 1920x1200 +0+0"

## RandR 1.1 Rotation Behavior

On X servers that support RandR 1.2 or later, when an RandR 1.1 rotation request is received (e.g., `xrandr --orientation left`), the NVIDIA X driver will apply that request to an entire MetaMode. E.g., if you configure multiple monitors, either through a MetaMode or through RandR 1.2:

      xrandr --output DVI-I-2 --mode 1280x1024 --pos 0x0 \
        --output DVI-I-3 --mode 1920x1200 --pos 1280x0

      nvidia-settings --assign CurrentMetaMode="DVI-I-2: 1280x1024 +0+0, \
        DVI-I-3: 1920x1200 +1280+0"

Requesting RandR 1.1 rotation through `xrandr --orientation left`, will rotate the entire MetaMode, producing the equivalent of either:

      xrandr --output DVI-I-2 --mode 1280x1024 --pos 176x0 --rotate left \
        --output DVI-I-3 --mode 1920x1200 --rotate left --pos 0x1280

      nvidia-settings --assign CurrentMetaMode="DVI-I-2: 1280x1024 +176+0, \
        { Rotation=left }, DVI-I-3: 1920x1200 +0+1280 { Rotation=left }"

On X servers that do not support RandR 1.2 or later, the NVIDIA X driver does not advertise RandR rotation support. On such X servers, it is recommended to configure rotation through MetaModes, instead.

## Output Properties

The NVIDIA FreeBSD driver supports a number of output device properties.

### Official Properties

Properties that do not start with an underscore are officially documented in the file `randrproto.txt` in X.Org's randrproto package. See that file for a full description of these properties.

- `ConnectorNumber`

  This property groups RandR outputs by their physical connectors. For example, DVI-I ports have both an analog and a digital output, which is represented in RandR by two different output objects. One DVI-I port may be represented by RandR outputs `DVI-I-0` with `SignalFormat` `TMDS` (transition-minimized differential signaling, a digital signal format) and `DVI-I-1` with `SignalFormat` `VGA`, representing the analog part. In this case, both RandR outputs would have the same value of `ConnectorNumber`.

- `ConnectorType`

  This property lists the physical type of the connector. For example, in the DVI-I example above, both `DVI-I-0` and `DVI-I-1` would have a `ConnectorType` of `DVI-I`.

- `EDID`

  This property contains the raw bytes of the display's extended display identification data. This data is intended for applications to use to glean information about the monitor connected.

- `SignalFormat`

  This property describes the type of signaling used to send image data to the display device. For example, an analog device connected to a DVI-I port might use VGA as its signaling format.

- `Border`

  This property is a list of integers specifying adjustments for the edges of the displayed image. How this property is applied depends on the number of elements in the list:

  - 0 = No border is applied.

  - 1 = A border of Border[0] is applied to all four sides of the image.

  - 2 = A border of Border[0] is applied to the left and right sides of the image, and a border of Border[1] is applied to the top and bottom.

  - 4 = The border dimensions are as follows: Border[0]: left, Border[1]: top, Border[2]: right, Border[3]: bottom

  This property is functionally equivalent to the ViewPortOut MetaMode token.

- `BorderDimensions`

  This property lists how many Border adjustment parameters can actually be used. The NVIDIA implementation supports independently configuring all four Border values.

- `GUID`

  DisplayPort 1.2 specifies that all devices must have a globally-unique identifier, referred to as a GUID. When a GUID is available, the `GUID` property contains its raw bytes.

- `CscMatrix`

  This property controls the color-space conversion matrix applied to the pixels being displayed. The matrix is 3 rows and 4 columns, stored in row-major order. Each entry is a 32-bit fixed-point number with 3 integer bits and 16 fractional bits. Each entry in the X colormap is treated as a 4-component column vector C = [ R, G, B, 1 ]. The resulting components of the color vector [ R', G', B' ] = CscMatrix * C are used as indices into the gamma ramp.

  For example, using xrandr version 1.5.0 or higher, you can exchange the red channel with the green channel using this command:

        xrandr --output DP-6 --set CscMatrix \
          0,0x10000,0,0,0x10000,0,0,0,0,0,0x10000,0

  To return to the default identity matrix, use

        xrandr --output DP-6 --set CscMatrix \
          0x10000,0,0,0,0,0x10000,0,0,0,0,0x10000,0

### Unofficial Properties

Properties whose names begin with an underscore are not specified by X.Org. They may be removed or modified in future driver releases. The NVIDIA FreeBSD driver supports the following unofficial properties:

- `_ConnectorLocation`

  This property describes the physical location of the connector. On add-in graphics boards, connector location 0 should generally be the position closest to the motherboard, with increasing location numbers indicating connectors progressively farther away.

  Type | INTEGER
  Format | 32
  # Items | 1
  Flags | Immutable, Static
  Range | 0-

## DisplayPort 1.2

When display devices are connected via DisplayPort 1.2 branch devices, additional RandR outputs will be created, one for each connected display device. These dynamic outputs will remain as long as the display device is connected or used in a MetaMode, even if they are not named in the current MetaMode. They will be deleted automatically when the display is disconnected and no MetaModes use them.

See Appendix C, Display Device Names for a description of how the names of these outputs are generated.

If you are developing applications that use the RandR extension, please be aware that outputs can be created and destroyed dynamically. You should be sure to use the XRRSelectInput function to watch for events that indicate when this happens.

## Monitor Configuration Options

This NVIDIA FreeBSD driver honors the `Enable`, `Ignore`, `Primary`, and `Rotate` options in the Monitor section of the X configuration file. These options will apply to a monitor if the Identifier of the Monitor section matches one of the display device's names (see Appendix C, Display Device Names for a description of how a display's names are generated). For example, a Monitor section with

      Identifier "DFP"

will apply to all digitally-connected displays, while a Monitor section with

      Identifier "DPY-EDID-ee6cecc0-fa46-0c33-94e0-274313f9e7eb"

will apply only to a display device with a specific EDID-based identification hash. You can also specify the name of the Monitor section to use in the Screen section:

      Option "Monitor-<dpyname>" "<Monitor name>"

See the xorg.conf(5) man page for a description of these options.

## Known Issues

- Rotation and Transformations (configured either through RandR or MetaModes) are not yet supported with the GLX_NV_swap_group OpenGL extension.

- Some of the RandR 1.2 X configuration options provided by the XFree86 DDX implementation and documented in xorg.conf(5) are not yet supported.

- Transformations (configured either through RandR or MetaModes) are not yet correctly clipped.

Prev | Up | Next
Chapter 13. Configuring Multiple X Screens on One Card | Home | Chapter 15. Configuring a Notebook