- fbconfig module for configuring SunXVR-4000 Graphics Accelerator
fbconfig [-dev device-filename] [-file machine | system] [options... | -defaults]
fbconfig [-dev device-filename] [-propt] [-prconf]
fbconfig [-dev device-filename] [-list | -help | -res \?]
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 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]]]
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.
The many options that fbconfig can select on the Sun XVR-4000 Graphics Accelerator are divided into the following categories:
Shared among different invocation forms or used for query without selecting device settings.
Of the entire XVR-4000 Graphics Accelerator, shared between up to two video streams.
Pertain to an area of the frame buffer managed by X and possibly shared between two video streams.
Specific to a video stream.
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 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 \? options, provides 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/config/Xservers.
This section is subdivided into general, card, managed area, and stream options.
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.
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.
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.
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)
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
Displays a list of the SUNWzulu_config command line options, along with a brief explanation of each.
Displays list of defined video mode names supported by the XVR-4000 Graphics Accelerator and the display device.
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.
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.
Controls the internal routing of video streams to output ports (that is, backplane 13W3 connectors). The choices are:
Stream a to output port a, stream b to output port b
Stream a to output port b, stream b to output port a
Stream a to both output ports
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.
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.
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.
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:
The elements of the specifier are described as follows:
This can be one of:
Video Electronics Standards Association-derived resolution
This can be one or more of:
normal resolution, usable by most display devices
resolution tuned only for LCD flat panels
screen width in pixels
screen height in pixels
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 \? option.
The -multisample option controls whether a multisample buffer is allocated by the window system and used by OpenGL applications. The suboptions are:
No multisample rendering is possible. Only one sample per pixel is allocated, despite the -samples option value. Furthermore, display filtering is disabled.
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.)
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.
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 follow.
The default is max, which means to use the maximum number of samples 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 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 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 combination 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.
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:
Samples are regularly-spaced both vertically and horizontally. The sample locations repeat every pixel or two in X and Y.
Samples are pseudo-randomly (irregularly) spaced within the pixel. The sample locations repeat every 2 pixels in X and Y.
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.
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 sample 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.
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.
There are two ways to configure filtering. The -filter option is the simpler. It selects from these predefined filters:
Poorest visual quality, most like a box filter.
Blurriest; suitable for users who want to forgo detail to avoid all visible sampling artifacts.
The best photo-realistic compromise between sharp detail and noticeable blurriness. This filter is the default.
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 filter_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.
Offsets the display of the stream (specified by -stream) relative to the adjoining edge of the other stream when doublewide or doublehigh is enabled. This can be used to cause an overlap.
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.
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.
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 displayed using gamma-corrected visuals. The gamma correction value is also saved in the OWconfig file for the next time the window system starts.
This option allows you to enable a synchronization technique for the specified stream. Available techniques:
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 signal have the same frame rate as the stream's video format.
When using framelock (or bothlock), you can also specify the synchronization source:
Indicates that the sync source is the other stream of this device.
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.
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.
This enables both framelock and genlock techniques, and requires both framelock (if external) and genlock cables.
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.
Reset all genlock details to their defaults.
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.
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.
This option controls the details of input sync signal sampling, if necessary:
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.
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.
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.
Synchronize to a tri-level signal, used by HDTV analog formats.
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.
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.
Synchronize with a rising edge of a sync pulse.
Synchronize with a falling edge of a sync pulse.
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
default device file
device configuration program
root file system directory for filter files
/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:
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.