SUNWzulu_config(1M) System Administration Commands SUNWzulu_config(1M)NAMESUNWzulu_config - fbconfig module for configuring SunXVR-4000 Graphics
Accelerator
SYNOPSIS
fbconfig [-dev device-filename] [-file machine | system] [options... |
-defaults]
fbconfig [-dev device-filename] [-propt] [-prconf]
fbconfig [-dev device-filename] [-list | -help | -res .PP fbconfig
[-dev device-filename] [-doublewide enable | disable] [-doublehigh
enable | disable] [-outputs direct | swapped | streamA | streamB]
[-master a | b] [-clearpixel 0 | 255]
fbconfig [-dev device-filename] [-res video_mode] [-multisample avail‐
able | disable | forceon] [-samples samples-per-pixel] [-jitter regular
| random | permuted | auto]
fbconfig [-dev device-filename] [-stream a | b] [-filter cylinder |
gaussian | mitchell | catmull] -filter_file filter_filename [-offset
xoff-value yoff-value] [-g gamma-correction-value] [-slave [ enable |
disable] [framelock [internal | external] | genlock | bothlock]]
[-genlock [defaults] [hphase ±hphs] [vphase ±vphs] [sync [auto |tip |
tri | slice]] [pol [auto | pos | neg]]]
DESCRIPTIONSUNWzulu_config is the Sun XVR-4000 Graphics Accelerator device-depen‐
dent layer for fbconfig(1M). It configures the Sun XVR-4000 Graphics
Accelerator and some of the X11 window system defaults and some inter‐
actions with 3D-accelerated graphics (through OpenGL).
The first through third synopses, above, show the general form of a
SUNWzulu_config command. The fourth synopsis (with -res as the first
option) shows card options. The fifth synopsis is for managed-area
options. The sixth and last synopsis shows stream options. These option
categories—card, managed-area, and streams—are used mainly to explain
the SUNWzulu_config functions. Where appropriate, you can use options
of different types on the same command line.
The Sun XVR-4000 device can support one or two unique video streams
(called stream a and stream b), each of which can drive a display
device.
Option Classes
The many options that fbconfig can select on the Sun XVR-4000 Graphics
Accelerator are divided into the following categories:
general options
Shared among different invocation forms or used for query without
selecting device settings.
card options
Of the entire XVR-4000 Graphics Accelerator, shared between up to
two video streams.
managed area options
Pertain to an area of the frame buffer managed by X and possibly
shared between two video streams.
stream options
Specific to a video stream.
Device Usage and Invocation Forms
To use the device to provide a single X managed area with one video
stream, use a stream-independent device argument (for example, -dev
zulu0) without a trailing a or b. The device name (for example, /dev/fb
or /dev/fbs/zulu0), without any trailing stream indicator should appear
on the Xsun command line. Stream options will control stream a (the
only stream used).
To enable two streams from a single X managed area (without needing X's
+xinerama option), use the device name (for example, -dev zulu0) with‐
out any trailing a or b. Enable card option -doublewide or -doublehigh.
Without using the -stream option, any stream options you specify are
applied to both streams. Stream options can differ between the video
streams if fbconfig is be run separately for each stream, using the
-stream a | b option, as shown in EXAMPLES (second example), below.
To use the device's two streams as independent X screens, run fbconfig
separately for each stream (-dev zulu0a and -dev zulu0b), as shown in
EXAMPLES (third example). Card options -doublehigh and -doublewide are
not available. The device names with trailing stream indicators (for
example, /dev/fbs/zulu0a and /dev/fbs/zulu0b) must be added to the Xsun
command line to use these independent X screens. The -stream option is
not needed; the stream is implied by the stream-specific device name.
The fbconfig utility checks settings for the two stream devices to
assure X can use them simultaneously. Therefore, you might need to use
fbconfig to reduce resouce consumption (for example, -samples) used by
one stream's device (for example, zulu0a) before you can use fbconfig
to increase consumption by the other stream's device (for example,
zulu0b).
The first form of SUNWzulu_config shown in SYNOPSIS, above, stores the
specified options in the OWconfig file associated with the device and
(for stream options) the stream. These options are used to initialize
the device the next time the window system is started on that device-
filename. Updating options in the OWconfig file provides persistence of
these options across window system sessions and system reboots. You can
select the OWconfig file that is to be updated using the -file option.
For -jitter and all stream options, the device will also be immediately
programmed.
The second form, which invokes any of the -prconf and -propt options,
queries the device for status that is card-specific.
The third form, which invokes the -help, -list, or -res instruction on
using SUNWzulu_config, a list of available devices, or a list of avail‐
able resolutions. When using this form, all other options are ignored.
You can specify options for only one device at a time. Specifying
options for multiple devices (or multiple independent X managed areas
or streams) requires multiple invocations of fbconfig.
Only Sun XVR-4000 Graphics Accelerator-specific options can be speci‐
fied through SUNWzulu_config. Window system options for specifying
default depth, default visual class, -nobanner, and so forth are still
specified as device modifiers on the Xsun command line when the X
server is started, probably in CDE's Xservers file. See the Xsun(1) man
page in the OpenWindows man page collection and /usr/dt/con‐
fig/Xservers.
OPTIONS
This section is subdivided into general, card, managed area, and stream
options.
General Options
-dev device-filename
Specifies the device's special file, such as /dev/fbs/zulu0 or the
basename such as zulu0 as a shorthand. The default is /dev/fb. See
"Device Usage and Invocation Forms," above.
-file machine|system
Specifies which OWconfig file to update. If machine is specified,
the machine-specific OWconfig file in the /etc/openwin directory
tree is updated. If system is specified, the global OWconfig file
in the /usr/openwin directory tree is updated. If the specified
file does not exist, it is created. This option has no effect
unless other options are specified. The default is machine.
-defaults
Resets all option values to their default values, listed in the
DEFAULTS section, below. For example, invoking -defaults on zulu0,
zulu0a, or zulu0b will reset all card, managed area, and stream
options for all these zulu0 subdevices.
-propt
Displays the current values of all options in the OWconfig file
specified by the -file option for the device specified by the -dev
option. Displays the values of options as they will be in the
OWconfig file after the call to SUNWzulu_config completes. The fol‐
lowing is an example display:
--- OpenWindows Configuration for /dev/fbs/zulu0 ---
OWconfig File: machine
Card:
Double(wide/high): disable
Stream to Port Mapping: direct (Stream A to Port A; B to B)
Clearpixel Value: 255
Managed Area:
Resolution: SUNW_STD_1280x1024x76
Samples Per Pixel: max
Multisample Mode: forceon
Jitter Table: auto
Video Streams:
Stream A:
Offset (x,y): (0, 0)
Gamma Correction Value: 2.22
Filter Type: mitchell
Stream B:
Offset (x,y): (0, 0)
Gamma Correction Value: 2.22
Filter Type: mitchell
Framelock:
Framelock/Stereo Port: Output from Stream A
Stream A Sync: Free Run (no frame sync)
Stream B Sync: Free Run (no frame sync)
-prconf
Displays the current XVR-4000 hardware configuration, including
version numbers of each class of chip. The following is an example
display:
--- Hardware Configuration for /dev/fbs/zulu0 ---
Type: XVR-4000 Graphics Accelerator
Part: 501-5588
Memory:
MAJC: 128MB
Texture: 1GB total
3DRAM64: 10.0M samples
Versions:
Fcode 1.19 MCode 1.4 MAJC 2.1
FBC3 3.0 Master 1.0 Convolve 0.0
Sched 1.0 I/O 1.0 FPGA 0.0
Power Level:
Monitor Power: On
Board Power: On
Video Streams:
Stream A:
Current resolution setting: SUNW_STD_1280x1024x76
Flags: Allocated Default Primary
Samples per pixel: 6
Port: 13W3a
Monitor/EDID data (13W3)
Monitor Manufacturer: SUN
Monitor Name: GDM-5410
EDID: Version 1, Revision 2
Stream B:
Current resolution setting: SUNW_STD_1280x1024x76
Flags: Allocated
Samples per pixel: 2
Port: 13W3b
Monitor/EDID data (13W3)
Monitor Manufacturer: SUN
EDID: Version 1, Revision 3
-help
Displays a list of the SUNWzulu_config command line options, along
with a brief explanation of each.
-res .sp .6
Displays list of defined video mode names supported by the XVR-4000
Graphics Accelerator and the display device.
Card Options
-doublewide enable | disable
This option makes it easy for you to combine both streams into one
side-by-side virtual display. When enabled with -outputs direct,
stream a is to the left of stream b. Both streams will use the same
video mode defined with the -res option. If you specify disable,
only stream a will be enabled. Enabling -doublewide disables -dou‐
blehigh.
-doublehigh enable | disable
This option makes it easy for you to combine both streams into one
virtual display with one display device above the other. When
enabled with -outputs direct, stream a is above stream b. Both
streams will use the same video mode defined with the -res option.
If you specify disable, only stream a will be enabled. Enabling
-doublehigh disables -doublewide.
-outputs direct | swapped | streamA | streamB
Controls the internal routing of video streams to output ports
(that is, backplane 13W3 connectors). The choices are:
direct
Stream a to output port a, stream b to output port b
swapped
Stream a to output port b, stream b to output port a
streamA
Stream a to both output ports
streamB
Stream b to both output ports
The default is direct. swapped can be used to reverse the connec‐
tors when -doublewide or -doublehigh is enabled. The streamA and
streamB arguments are incompatible with stream-specific device
names (for example, zulu0a or zulu0b). When the -res option selects
an S-video (NTSC or PAL composite) video mode, the svideo output
port is automatically selected, sometimes overriding -outputs
selection.
-master a | b
This option controls which stream drives the FIELD and FRAME_OUT
pins on the device's stereo/sync connector. This pin can drive
stereo shutter glasses, and allow another device to framelock to
this device's output. The default is a.
Independent of this option, the -slave external option allows a
stream to sync to another card by means of this connector's
FIELD_IN pin.
-clearpixel 0 | 255
Selects the overlay transparent color. This is the pixel value
(color index) used by the transparent overlay visual to display the
underlay (RGB) pixel contents. The default is 255 (all bits 1), but
some applications require 0. All other color indices display a
colormap color.
Managed Area Options
-res video_mode
The video_mode argument specifies resolution and timing information
for the display (for example, SUNW_STD_1280x1024x76). The naming
convention for the video mode specifier is:
origin_type_widthxheightxrate
The elements of the specifier are described as follows:
origin
This can be one of:
SUNW
Sun-derived resolution
VESA
Video Electronics Standards Association-derived resolution
other
other source
type
This can be one or more of:
STD
normal resolution, usable by most display devices
DIG
resolution tuned only for LCD flat panels
INT
interlaced
STEREO
stereo
width
screen width in pixels
height
screen height in pixels
rate
vertical frequency of the screen refresh (in hertz, that is,
video frames per second)
Note that some video modes supported by the XVR-4000 might not be
supported by the display device. The list of video modes supported
by the device and the display device can be obtained by running
SUNWzulu_config with the -res .sp
-multisample available | disable | forceon
The -multisample option controls whether a multisample buffer is
allocated by the window system and used by OpenGL applications.
The suboptions are:
disable
No multisample rendering is possible. Only one sample per pixel
is allocated, despite the -samples option value. Furthermore,
display filtering is disabled.
available
Multisample is possible but is selected on a per-application
basis. (Each process may choose whether to multisample at the
density allocated when the window system started, or not to
multisample at all. Intermediate densities are not possible.)
forceon
Sun OpenGL will use multisample rendering for all applications.
There may be a minor performance penalty for rendering at
higher sample densities.
Multisample allocation occurs when the window system starts up.
This is the only allocation mode supported on the Sun XVR-4000
Graphics Accelerator.
-samples samples-per-pixel
Specifies the number of samples per pixel to allocate when multi‐
sample is not disable. Allowable choices are 1 to 16 or max, but a
very high sample density can be allocated only at low resolution.
Setting sample density to 1 is not equivalent to disabling multi‐
sampling; samples will still be subject to filtering and jitter.
Sample resolutions (without frame rates) and their maximum sample
densities follow.
Resolution Maximum Density Maximum Balanced Density
width by height (single stream) (one stream + another)
1920 by 1200 4 samples 2 + 2 samples
1600 by 1200 5 samples 3 + 2 samples
1600 by 1024 6 samples 3 + 3 samples
1280 by 1024 8 samples 4 + 4 samples
1152 by 900 9 samples 5 + 4 samples
1024 by 800 11 samples 5 + 5 samples
800 by 600 15 samples 7 + 7 samples
768 by 575 15 samples 7 + 7 samples
640 by 480 16 samples 9 + 9 samples
The default is max, which means to use the maximum number of sam‐
ples that can be supported with the amount of memory available,
possibly dependent on the video timing (horizontal frequency).
For dual independent streams, if the first stream used by the win‐
dow system (typically, the first in the Xservers file) chooses max,
it takes most of the memory and video resources. The second stream
can then use only a low sample density. If it also chooses max, X
automatically finds the highest sample density remaining, such as 1
or 2 samples per pixel. To assign sample density more evenly, set
each stream's density explicitly. SUNWzulu_config allows a combina‐
tion of resolutions and sample densities only if they will coexist
successfully. You might have to reduce one stream's sample density
(or choose max) before you can increase the other stream's.
-jitter regular | random | permuted | auto
Indirectly determines the subpixel (X,Y) locations of the samples
stored in the sample buffer. (The sample density also affects the
sample locations.) Choices are:
regular
Samples are regularly-spaced both vertically and horizontally.
The sample locations repeat every pixel or two in X and Y.
random
Samples are pseudo-randomly (irregularly) spaced within the
pixel. The sample locations repeat every 2 pixels in X and Y.
permuted
Samples are pseudo-randomly spaced within the pixel, and also
permuted (stirred) in hardware so that the sample locations
repeat every 128 pixels in X and Y. At moderate to high sample
density, this choice can improve visual quality. At low sample
density, straight lines or edges can appear jagged.
auto
Automatically selects the best jitter option for the current
sample density. This is the default.
The same jitter selection must be used by OpenGL when rendering and
by the display subsystem when refreshing the display from the sam‐
ple buffer. The jitter value is changed immediately in hardware,
but any multisamples already in the sample buffer were rendered
using the prior jitter selection; that will look incorrect (for
example, unstraight lines or edges) if the jitter selection is
changed.
When a new OpenGL application starts up, it will render using the
new jitter selection. (The window system need not be restarted.)
The jitter value is also saved in the OWconfig file for the next
time the window system starts.
Stream Options
-stream a | b
Determines whether stream options will be set for stream a or
stream b. The "Device Usage and Invocation Forms" section, above,
describes the usage and the default. The -stream option is
required only to set different stream options for the two video
streams enabled using card option -doublewide or -doublehigh.
-filter cylinder | gaussian | mitchell | catmull
-filter_file filter_filename
There are two ways to configure filtering. The -filter option is
the simpler. It selects from these predefined filters:
cylinder
Poorest visual quality, most like a box filter.
gaussian
Blurriest; suitable for users who want to forgo detail to avoid
all visible sampling artifacts.
mitchell
The best photo-realistic compromise between sharp detail and
noticeable blurriness. This filter is the default.
catmull
The Catmull-Rom filter produces images a little sharper than
Mitchell, but are more likely to have visible sampling arti‐
facts, widely known as "jaggies".
The -filter_file option allows a user to provide his own filter by
producing a filter file and copying or linking it into the direc‐
tory /etc/openwin/server/etc/filters or /usr/open‐
win/server/etc/filters. (Both directories are writable by super-
user by default.) The filter_filename must not start with / or ../
nor contain the substring /../, but can contain subdirectory compo‐
nents.
fbconfig and X search the directories above in the order listed. If
the filter_filename is present and valid, the file takes precedence
over a predefined filter.
The format of the file is a sequence of floating-point radius and
weight values, each value separated by whitespace. Radius values
must be monotonically increasing from 0. Weight values must be
between -1.0 and +1.0, inclusive. Though more values can be
present in the file, only values through radius 2.0 are used.
Whitespace and comment lines prefixed with a hash mark (#) are
ignored.
Example files contain the (irregular) radius values for which the
device uses weight values. The file reader interpolates between
existing values if the required radius is not present.
A valid filter option is changed immediately in hardware and saved
in the OWconfig file for the next time the window system starts.
However, when multisample is disabled, no filtering occurs.
-offset xoff-value yoff-value
Offsets the display of the stream (specified by -stream) relative
to the adjoining edge of the other stream when doublewide or dou‐
blehigh is enabled. This can be used to cause an overlap.
xoff-value
Number of pixels offset in horizontal direction for the right‐
hand stream when doublewide is enabled. Positive direction is
to the right (create a gap); negative is to the left (overlap
the streams). Default is 0, which means the two edges abut.
yoff-value
Number of pixels offset in vertical direction for the bottom
stream when doublehigh is enabled. Positive direction is down
(create a gap); negative is up (overlap the streams). Default
is 0, which means the two edges touch.
-g gamma-correction-value
This option changes the gamma correction value. By default the
gamma correction value is 2.22. Any value less than zero is ille‐
gal. This option can be used while the window system is running.
Changing the gamma correction value will affect all the windows
being displayed using gamma-corrected visuals. The gamma correction
value is also saved in the OWconfig file for the next time the win‐
dow system starts.
-slave [enable | disable]
[framelock [internal | external] | genlock | bothlock ]
This option allows you to enable a synchronization technique for
the specified stream. Available techniques:
framelock [internal | external]
This provides "asynchronous frame reset": multiple streams all
start a frame at roughly the same time. This allows stereo
shutters to view the same eye's image from all the synchronized
display devices. Using framelock requires the incoming synchro‐
nization signal have the same frame rate as the stream's video
format.
When using framelock (or bothlock), you can also specify the
synchronization source:
internal
Indicates that the sync source is the other stream of this
device.
external
Indicates the sync is taken from a source outside the
device. Using external requires a Frame Lock Cable (part
number 530-2754) to be connected. If -slave enable is used
without specifying a technique, framelock external is used.
genlock
This provides pixel-accurate horizontal synchronization, which
is important in some video mixing situations. Use of genlock
requires a genlock cable. Use of bothlock is recommended, when
possible. Certain video formats are incompatible with genlock.
bothlock
This enables both framelock and genlock techniques, and
requires both framelock (if external) and genlock cables.
-genlock [defaults] [hphase ±hphs][vphase ±vphs]
[sync [ auto|tip|tri|slice ] ] [ pol [ auto|pos|neg ] ]
When -slave is enabled and the genlock technique is selected, the
selections chosen with the -genlock option determine genlock
details. These details are used immediately by the hardware, and
saved in the OWconfig file for future use. Note that they may no
longer be desired after changing to a different video format.
defaults
Reset all genlock details to their defaults.
hphase ±hphs
The horizontal phase allows a pixel offset between the external
video format and the stream's output. It may be specified as an
absolute integer ranging from 0 to the total number of pixel
clocks in a horizontal period (active video plus blanked pix‐
els). Or, if the hphs starts with a + or -, the value will be
added to the current horizontal phase and and saved, modulo the
valid range. Small deltas can be used repeatedly until the
desired effect is observed.
vphase ±vphs
The vertical phase allows a scanline offset between the exter‐
nal video format and the stream's output. It can be specified
as an absolute integer ranging from 0 to the total number of
scanlines in a frame (active video plus blanked scanlines). Or,
if the vphs starts with a + or -, the value will be added to
the current vertical phase and and saved, modulo the valid
range. Small deltas can be used repeatedly until the desired
effect is observed.
sync [auto|tip | slice | tri]
This option controls the details of input sync signal sampling,
if necessary:
auto
Sample the genlock input pulses as most appropriate for the
(Sun) video format. This is the default, and should be used
whenever the sync master is also a Sun video format.
tip
Consider the sync to have occurred at the minimum signal
value. This can be used with RS-170 (NTSC or PAL) or with
TTL signals.
slice
Consider the frame sync to have occurred halfway between
the minimum and maximum value (sync tip and back porch
"blank" levels). This can be used with RS-170 (NTSC or PAL)
or with TTL signals.
tri
Synchronize to a tri-level signal, used by HDTV analog for‐
mats.
pol [auto|pos|neg]
When the sync master is not a Sun video format, it might be
necessary to choose which edge of the genlock input sync pulse
should be used for genlock.
auto
Choose rising or falling edge for sync pulse, whichever is
most appropriate for the video format. This is the default,
and should be used whenever the sync master is also a Sun
video format.
pos
Synchronize with a rising edge of a sync pulse.
neg
Synchronize with a falling edge of a sync pulse.
DEFAULTS
For a given invocation of SUNWzulu_config, if an option does not appear
on the command line, the corresponding OWconfig option is not updated.
It retains its previous value.
When the window system starts, if an option has never been specified
through SUNWzulu_config, a default value is used. The option defaults
are as follows:
Option Class Option Default
General -dev /dev/fb
General -file machine
(/etc/openwin/server/etc/OWconfig)
Card -doublewide disable
Card -doublehigh disable
Card -master a
Card -outputs direct
Card -clearpixel 255
Managed Area -res SUNW_STD_1280x1024x76
Managed Area -multisample forceon
Managed Area -samples max
Managed Area -jitter auto
Stream -offset 0,0
Stream -filter mitchell
Stream -slave disable/external/framelock
Stream -genlock hphase 0/vphase 0/auto/auto
Stream -g 2.22
EXAMPLES
Example 1: Switching Resolution of a Monitor
The following example switches to the resolution of 1280 by 1024 at 76
hertz:
% fbconfig -dev zulu0 -res SUNW_STD_1280x1024x76
Example 2: Using Two Side-by-side Monitors with One Large X Screen
The following example enables use of two side-by-side monitors to dis‐
play together a single large shared X window system "screen" (frame
buffer managed area):
% fbconfig -dev zulu0 -doublewide enable
If the wrong monitor is on the left, they can be swapped in software:
% fbconfig -dev zulu0 -outputs swapped
A stream option selects a Gaussian (blurry) filter for video stream b:
% fbconfig -dev zulu0 -stream b -filter gaussian
For the two examples above, the factory-installed /usr/dt/con‐
fig/Xservers file is sufficient (if /dev/fb is a link to the Sun
XVR-4000 Graphics Accelerator device). If an /etc/dt/config/Xservers
file exists, for Example 1 or 2, the file would refer to device zulu0
(not zulu0a or zulu0b):
:0 Local local_uid@console root /usr/openwin/bin/Xsun -dev /dev/fbs/zulu0
Example 3: Using Two Displays as Independent X Screens
The following example enables use of two displays, each with their own
X window system managed frame buffer area and resolution. The larger
resolution is not multisampled or filtered, so the smaller resolution
will have more samples available to it.
% fbconfig -dev zulu0a -res SUNW_STD_1920x1200x75 -multisample disable
% fbconfig -dev zulu0b -res SUNW_STD_1280x1024x76 -samples max
In this example, and assuming the display device for stream b is to the
right of that for stream a, the /etc/dt/config/Xservers file might con‐
tain (as one long line):
:0 Local local_uid@console root /usr/openwin/bin/Xsun -nobanner
-dev /dev/fbs/zulu0a -dev /dev/fbs/zulu0b right
FILES
/dev/fb
default device file
/usr/lib/fbconfig/SUNWzulu_config
device configuration program
/etc/openwin/server/etc/filters/
root file system directory for filter files
/usr/openwin/server/etc/filters/
/usr file system directory for filter files
An administrator might also have to edit /etc/dt/config/Xservers.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWzuluc │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOfbconfig(1M), attributes(5)
See the dtlogin(1) man page in the CDE man page collection. Also use‐
ful is the Xsun(1) man page in the OpenWindows man page collection.
SunOS 5.10 8 Apr 2004 SUNWzulu_config(1M)