Content-type: text/html Man page of SUNWzulu_config

SUNWzulu_config

Section: System Administration Commands (1M)
Updated: 8 Apr 2004
Index Return to Main Contents
 

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 ?]

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]]]  

DESCRIPTION

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 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.  

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 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 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 ?

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 ? option.

-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 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.

ResolutionMaximum DensityMaximum Balanced Density
width by height(single stream)(one stream + another)
1920 by 12004 samples2 + 2 samples
1600 by 12005 samples3 + 2 samples
1600 by 10246 samples3 + 3 samples
1280 by 10248 samples4 + 4 samples
1152 by 9009 samples5 + 4 samples
1024 by 80011 samples5 + 5 samples
800 by 60015 samples7 + 7 samples
768 by 57515 samples7 + 7 samples
640 by 48016 samples9 + 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, 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.

-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 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.

 

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 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.

-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 doublehigh 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 displayed 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 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 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 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 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

 

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 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 [email protected] 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 [email protected] 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 TYPEATTRIBUTE VALUE
AvailabilitySUNWzuluc

 

SEE ALSO

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.


 

Index

NAME
SYNOPSIS
DESCRIPTION
Option Classes
Device Usage and Invocation Forms
OPTIONS
General Options
Card Options
Managed Area Options
Stream Options
DEFAULTS
EXAMPLES
FILES
ATTRIBUTES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:37:09 GMT, October 02, 2010