SUNWzulu_config(1M) SUNWzulu_config(1M)
NAME
SUNWzulu_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 available | disable | forceon] [-samples samples-per-pixel] [-jitter regu-
lar | 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]]]
SUNWzulu_config is the Sun XVR-4000 Graphics Accelerator device-dependent layer for fbconfig(1M). It configures the Sun XVR-4000 Graphics
Accelerator and some of the X11 window system defaults and some interactions 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)
without any trailing a or b. Enable card option -doublewide or -doublehigh. Without using the -stream option, any stream options you spec-
ify 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 (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 (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 fbcon-
fig to increase consumption by the other stream's device (for example, zulu0b).
The first form of SUNWzulu_config shown in , 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-file-
name. 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 immedi-
ately 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
available 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 specified 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.
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 following
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 dis-
play:
--- 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 -doublehigh.
-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 connectors 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, dis-
play 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 multisample 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 multisampling;
samples will still be subject to filtering and jitter. Sample resolutions (without frame rates) and their maximum sample densities fol-
low.
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 samples that can be supported with the amount of memory available, possi-
bly dependent on the video timing (horizontal frequency).
For dual independent streams, if the first stream used by the window 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 auto-
matically 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 combination of resolutions and sample densities only if they will coexist suc-
cessfully. 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 artifacts,
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 directory
/etc/openwin/server/etc/filters or /usr/openwin/server/etc/filters. (Both directories are writable by super-user by default.) The fil-
ter_filename must not start with / or ../ nor contain the substring /../, but can contain subdirectory components.
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 double-
high is enabled. This can be used to cause an overlap.
xoff-value
Number of pixels offset in horizontal direction for the righthand 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 illegal.
This option can be used while the window system is running. Changing the gamma correction value will affect all the windows being dis-
played using gamma-corrected visuals. The gamma correction value is also saved in the OWconfig file for the next time the window 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 synchronization sig-
nal 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 pixels). 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 external 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 when-
ever 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" lev-
els). 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 formats.
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
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 display 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/config/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
contain (as one long line):
:0 Local local_uid@console root /usr/openwin/bin/Xsun -nobanner
-dev /dev/fbs/zulu0a -dev /dev/fbs/zulu0b right
/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.
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Availability |SUNWzuluc |
+-----------------------------+-----------------------------+
fbconfig(1M), attributes(5)
See the dtlogin(1) man page in the CDE man page collection. Also useful is the Xsun(1) man page in the OpenWindows man page collection.
8 Apr 2004 SUNWzulu_config(1M)