XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
NAME
XSGIvcListVideoFormats, XSGIvcListVideoFormatCombinations,
XSGIvcListVideoFormatsInCombination, XSGIvcLoadVideoFormat,
XSGIvcLoadVideoFormatCombination, XSGIvcDisableChannel-
Video Format Query and Load Functions
SYNOPSIS
#include <X11/extensions/XSGIvc.h>
XSGIvcVideoFormatInfo *XSGIvcListVideoFormats(Display *display,
int screen,
int channel,
const XSGIvcVideoFormatInfo * pattern,
unsigned long querymask,
Bool matchMonitor,
int maxformats,
int *actual_count_return)
char **XSGIvcListVideoFormatCombinations(Display *display,
int screen,
const char *pattern,
int maxnames,
int *actual_count_return)
XSGIvcVideoFormatInfo *XSGIvcListVideoFormatsInCombination(Display *display,
int screen,
const char *combinationName,
int *actual_count_return)
Status XSGIvcLoadVideoFormat(Display *display,
int screen,
int channel,
const XSGIvcVideoFormatInfo * pattern,
unsigned long querymask,
Bool matchMonitor)
Status XSGIvcLoadVideoFormatCombination(Display *display,
int screen,
const char *combinationName)
XSGIvcVideoFormatInfo *XSGIvcNVListVideoFormats(Display *display,
int screen,
int channel,
const XSGIvcVideoFormatInfo * pattern,
unsigned long querymask,
Bool matchMonitor,
Bool matchOnlyNV,
int maxformats,
int *actual_count_return)
char **XSGIvcNVListVideoFormatCombinations(Display *display,
int screen,
Page 1 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
const char *pattern,
Bool matchOnlyNV,
int maxnames,
int *actual_count_return)
Status XSGIvcNVLoadVideoFormat(Display *display,
int screen,
int channel,
const XSGIvcVideoFormatInfo * pattern,
unsigned long querymask,
Bool matchMonitor,
int syncSource,
int externalSyncSource)
Status XSGIvcNVLoadVideoFormatCombination(Display *display,
int screen,
const char *combinationName)
Status XSGIvcLoadVideoFormatByName(Display *display,
int screen,
int channel,
const char *path)
Status XSGIvcNVLoadVideoFormatByName(Display *display,
int screen,
int channel,
const char *path)
Status XSGIvcDisableChannel(Display *display,
int screen,
int channel)
PARAMETER
display Specifies the connection to the X
server.
screen Specifies the screen of the X server.
channel Specifies the channel number.
pattern Specifies the structure which contains
the query description. All video
formats that match the query will be
returned (up to maxformats).
querymask Specifies which fields in pattern are
to be used for query. This mask is
the bitwise inclusive OR of the valid
query mask bits. If the querymask is
zero, all video formats will be
returned. Those attributes that are
set in the querymask are used to
Page 2 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
constrain the query. These fields are
manifest constants that have a prefix
of XSGIVC_QVF.
matchMonitor If True, restricts queries to those
formats which are within the operating
range of the monitor. If False, no
constraint check is made.
maxformats Specifies the maximum number of
XSGIvcVideoFormatInfo to be returned.
maxnames Specifies the maximum number of names
to be returned.
actual_count_return Returns the actual number of video
format names.
combinationName The name of the video format
combination
syncSource For the NV version of the load format
function, specifies the sync source.
Use XSGIVC_SYNC_SOURCE_EXTERNAL to
specify the external sync source,
XSGIVC_SYNC_SOURCE_INTERNAL to specify
the internal sync source.
matchOnlyNV If True, restricts queries to those
formats or combinations which cannot
be loaded with dynamic load functions
(XSGIvcLoadVideoFormat and
XSGIvcListVideoFormatCombinations) and
must be loaded by using the "NV"
(non-volatile) versions of those
functions. If False, all formats or
combinations are returned which can be
loaded using the "NV" versions of the
functions, including formats that can
also be loaded dynamically; those
formats which cannot be loaded with
the "NV" functions are not returned.
externalSyncSource For the NV version of the load format
function, specifies which external
sync source to use when syncSource is
set to XSGIVC_SYNC_SOURCE_EXTERNAL.
This parameter is undefined when
syncSource is set to
XSGIVC_SYNC_SOURCE_INTERNAL.
path The absolute path - including the file
Page 3 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
name - of a format or combination. If
no directory name is specified, the
reserved format or combination
directory is used; see description in
Load By Name below.
DESCRIPTION
The XSGIvcListVideoFormats() function returns an array of
available video format description structures
(XSGIvcVideoFormatInfo) that match a name pattern
specification. The XSGIvcListVideoFormatCombinations()
function returns a list of video format combination names
that match a query specification; the
XSGIvcListVideoFormatsInCombination() function returns video
format description structures (XSGIvcVideoFormatInfo) for a
named format.
If no video formats or combinations are available given the
query specification, the value 0 (zero) is returned in
actual_count_return.
The XSGIvcLoadVideoFormat function loads a video format into
the specified channel. The newly-loaded format completely
supplants the video format operating in the channel.
The method by which the video format is specified is similar
to the query performed in the function
XSGIvcListVideoFormats(3). You describe the desired video
format by populating the pattern structure, specifying the
meaningful fields (query constraints) via the querymask
parameter. In the circumstance where many video formats
meet the query requirements, the first format is loaded. To
unambiguously specify a video format, use the ByName forms
of the load.
You may disable a channel's output via XSGIvcDisableChannel.
This may have the effect of reducing overall demand on the
server while terminating output. It is not necessary to
disable a channel before loading a new video format. To
enable a channel after it has been disabled, use
XSGIvcLoadVideoFormat or XSGIvcLoadVideoFormatCombination.
Server hardware and software restrictions may not permit all
formats and combinations be loaded at any time. For
example, most servers do not permit the size of the root
window be changed: it is required that the server and
graphics subsystem restart to change the size.
Restrictions When Loading
On some graphics platforms, the size of the managed Screen
Page 4 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
is fixed, thus new formats and combinations must be equal to
or smaller in size (in both x- and y-dimensions) than the
current managed Screen; on those platforms, loading a format
or combination with a smaller size may not alter the
dimension of the managed Screen but simply display regions
within the larger area.
To load a format or combination whose size is larger than
the managed area, you must use the "NV" versions of the load
functions; see Non-Volatile Loading below.
Non-Volatile Loading
The special "NV" versions of the list and load functions,
XSGIvcNVListVideoFormats,
XSGIvcNVListVideoFormatCombinations,
XSGIvcNVLoadVideoFormat, and
XSGIvcNVLoadVideoFormatCombination, perform a list or load
of the non-volatile format or combination. That is, the NV
load functions load the format such that when the
graphics/video system is next started the new format will be
displayed; the list functions return those formats or
combinations which can be loaded when graphics are
restarted.
These "NV" load functions have no immediate effect on the
output as do the versions of the functions without the "NV"
designation. This is similar to the effect of the "-x"
option of setmon(1G).
Format combinations have sync source information embedded in
them. When loading individual formats, however, you must
specify the sync source to be used when graphics are
restarted; you do so in the manner described in
XSGIvcSetScreenInputSyncSource(3).
Load by Name
Normally, formats and combinations reside in a directory
reserved exclusively for such files. However, the functions
XSGIvcLoadVideoFormatByName and
XSGIvcNVLoadVideoFormatByName allow you to specify the name
of a file with an explicit path. If no directory
specification prefixes the file name, the reserved directory
is used.
The server may reject files that are not on local disks.
Query Specification Matching
To construct a query, populate a XSGIvcVideoFormatInfo
structure with values which are the constraints of the
Page 5 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
query. Specify which values in the structure are meaningful
via the querymask parameter which is the inclusive OR of all
supplied fields in the pattern structure. Fields which are
not represented in the mask are not used to constrain the
search (i.e., unconstrained fields are "don't care").
All query constrained fields must be an exact match. For
example, if fieldCount is specified as 2 and the querymask
parameter had the XSGIVC_QVFFieldCount bit set, this
function would return only those video formats that had two
fields.
To return every video format available to run on the
channel, specify the value 0 (zero) for querymask. You may
specify queries using the following bits in querymask:
XSGIVC_QVFHeight Matches the height in lines of the
active region of the format.
XSGIVC_QVFWidth Matches the width in pixels of the
active region of the format.
XSGIVC_QVFTotalHeight Matches the total number of lines of
the format, including blanking
lines.
XSGIVC_QVFTotalWidth Matches the total number of pixels
in each line of the format,
including blanking pixels.
XSGIVC_QVFRetraceRate Matches the retrace rate of the
format. Note this value is
specified as a floating-point
number; however, all comparisons are
integer-based. For this comparison,
the values are rounded to int by
adding 0.5 and truncating. For
example, 59.94Hz will be rounded to
60 before comparing.
XSGIVC_QVFSwapbufferRate
Matches the swapbuffer rate of the
format. This can be different from
the retrace rate in some video
formats. Note this value is
specified as a floating-point
number; however, all comparisons are
integer-based. For this comparison,
the values are rounded to int by
adding 0.5 and truncating. For
example, 29.97Hz will be rounded to
30 before comparing.
Page 6 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
XSGIVC_QVFFieldCount Matches the number of fields in the
format.
XSGIVC_QVFFlags Matches the formatFlags field of the
format.
Match Monitor Query
The field matchMonitor is a special constraint which
specifies the server should return only those video formats
whose timing requirements fall within the range supported by
the monitor connected to the channel (see
XSGIvcQueryMonitorName).
While this constraint gives some assurance a returned format
will operate successfully on the monitor connected to the
channel, it cannot be a guarantee. Nor can one be certain
that all formats will be returned that the connected monitor
can display. The specification of the range of operation of
a monitor and the description of the parameters of a video
format are not sufficiently exact to reliably predict a
proper match. Instead, consider this constraint to provide
a great likelihood that the returned formats are the best
matches for reliable operation.
This constraint further restricts the query above that which
you specify in querymask.
Video Format Names
Many SGI video formats have followed a standard naming
convention. This scheme is not guaranteed for future use
because it can be too ambiguous: the name itself is not
descriptive enough to distinguish between two different
formats. The convention for SGI standard video format names
has been:
WidthxHeight_FrameRate
where Height and Width specify the active portion of the
format (i.e., the visible portion of the frame displaying
pixels exclusive of the blanking regions). The FrameRate
specifies the frame rate in Hz, rounded to the nearest
integer.
The name of the format may be suffixed with a single-
character identifier which often has significance. This
suffix is a hint to the intended use of the format; detailed
information can be derived from the XSGIvcVideoFormatInfo
structure. Some meanings are:
Page 7 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
f The format is a variant of the standard format which can
lock to a dissimilar format.
i The format is interlaced
k Special alternative format
q The format has its colors displayed in serial fields
(color field sequential).
s The format is a stereo format
Note that the name is a general convention and not a
guarantee. For detailed information regarding the timing
specifications of a format, consult the returned structure.
For convenience and conformance with similar historical
operations, servers offer a set of aliases by which video
formats may also be referenced.
30HZ Equivalent to 1280x1024_30i
50HZ Equivalent to 1280x1024_50
60HZ Equivalent to 1280x1024_60
72HZ Equivalent to 1280x1024_72
NTSC A component RGB format containing timing pulses
similar to NTSC
PAL A component RGB format containing timing pulses
similar to PAL
343 Equivalent to 1280x960_30i. A component RGB
format similar to one of the RS-343 formats.
IRIS3K Equivalent to 1024x768_60
STR_RECT Full-screen stereo of the old SGI style. You
must also enable stereo rendering; see
XSGISetStereoMode(3X11).
Note that some servers may alter the structure of the video
format to conform to hardware restrictions. Also, not all
servers may have the capability to display all formats.
Some servers may list the same format under both its
conventional name and its alias.
Servers with Multiple Channels
Note that the XSGIvcLoadVideoFormat function may have
Page 8 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
different effects on some graphics platforms; notably,
platforms with multiple output channels may not support the
capability to load individual channels and instead require
use of the XSGILoadVideoFormatCombination(3) function which
loads a video format combination (i.e., an interoperating
set of video formats) into all channels with one call. To
determine whether the server supports loading channels
independently, see XSGIvcQueryVideoScreenInfo(3).
If you use XSGIvcLoadVideoFormat(3) on a server that does
not support loading channels independently, the server may
terminate output on all channels but the one to which the
format is loaded.
The output on other channels may be disrupted when loading a
video format to a channel.
Note that a change in any channel's video format must fall
within the operating range of a server. Certain
combinations of video formats on channels may exceed the
capabilities of the server and may be rejected.
Video Format Combinations
The XSGIvcListVideoFormatCombinations() function is used
with platforms that do not permit change of a single video
format and instead require that all formats be changed en
masse. This function returns an array of strings that match
a name specification you specify. The formats that comprise
a format combination may be queried via the function
XSGIvcListVideoFormatsInCombination. An array of video
format description structures (XSGIvcVideoFormatInfo) is
placed in the location you specify. Each element of the
array holds the structure video format that operates on the
channel number that corresponds to that array element (e.g.,
the video format in array element 3 corresponds to channel
3). If a format combination does not use a particular
channel, all values returned in the structure equal 0.
A pattern string is used as the criterion for the list of
video format combinations that are returned; the pattern
specifies the name of the combination. The pattern string
can contain any characters, but each asterisk (*) is a
wildcard for any number of characters, and each question
mark (?) is a wildcard for a single character.
STRUCTURES
/* Fields in querymask: XSGIvcListVideoFormats, XSGIvcLoadVideoFormat */
#define XSGIVC_QVFHeight (1L << 1)
#define XSGIVC_QVFWidth (1L << 2)
Page 9 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
#define XSGIVC_QVFTotalHeight (1L << 3)
#define XSGIVC_QVFTotalWidth (1L << 4)
#define XSGIVC_QVFRetraceRate (1L << 5)
#define XSGIVC_QVFSwapbufferRate (1L << 6)
#define XSGIVC_QVFFieldCount (1L << 7)
#define XSGIVC_QVFFlags (1L << 8)
/* See colorActive in XSGIvcFieldInfo */
#define XSGIVC_FIColorActiveRed (1L << 0)
#define XSGIVC_FIColorActiveGreen (1L << 1)
#define XSGIVC_FIColorActiveBlue (1L << 2)
#define XSGIVC_FIColorActiveAlpha (1L << 3)
/* See eyeActive in XSGIvcFieldInfo */
#define XSGIVC_FIEyeActiveLeft (1L << 0)
#define XSGIVC_FIEyeActiveRight (1L << 1)
typedef struct {
int offset; /* Line on which this field starts */
int stride; /* y-increment to next line */
struct {
int backPorch; /* Duration in pixels */
int sync; /* Duration in pixels */
int syncPulse; /* Duration in pixels */
int frontPorch; /* Duration in pixels */
int active; /* Duration in pixels */
} vertical;
long colorActive; /* Colors this field; XSGIVC_FI... */
long eyeActive; /* Eye this field; XSGIVC_FI... */
} XSGIvcFieldInfo;
/* See formatFlags in XSGIvcVideoFormatInfo */
#define XSGIVC_VFIStereo (1L << 0) /* Eye differs field to field */
#define XSGIVC_VFIFieldSequentialColor (1L << 1) /* Color differs field to field */
#define XSGIVC_VFIFullScreenStereo (1L << 2) /* SGI stereo of the old style */
typedef struct {
char name[XSGIVC_FORMATNAME_MAX]; /* Typically is filename */
int height, width; /* Active pixels */
int totalHeight; /* Includes blanking */
int totalWidth; /* Includes blanking */
float verticalRetraceRate;/* i.e., frame rate, in Hz */
float swapbufferRate; /* Can be different from frame rate */
int pixelClock; /* Pixels/second */
struct {
int backPorch; /* Duration in pixels */
int sync; /* Duration in pixels */
int frontPorch; /* Duration in pixels */
int active; /* Duration in pixels */
} horizontal;
int fieldCount;
XSGIvcFieldInfo *fieldInfo; /* Array of items, size=fieldCount */
Page 10 (printed 7/20/06)
XSGIvcListVideoFormats(3)XSGIvcListVideoFormats(3)
long formatFlags; /* See XSGIVC_VFI... fields */
} XSGIvcVideoFormatInfo;
RETURN VALUE
The XSGIvcListVideoFormats(),
XSGIvcListVideoFormatsInCombination(), and
XSGIvcNVListVideoFormats() functions return a list of
XSGIvcVideoFormatInfo structures.
The XSGIvcListVideoFormatCombinations() returns an array of
video format combination names (null-terminated strings).
The client should call XFree when finished with the result
to free the memory that was allocated.
If there are no matching video format names,
XSGIvcListVideoFormats returns NULL. The client should call
XFree when finished with the result to free the memory.
The functions XSGIvcLoadVideoFormat,
XSGIvcLoadVideoFormatCombination, and XSGIvcDisableChannel
return True if successful, False if unsuccessful.
EVENTS
When the format or combination changes, the server generates
a VideoFormatNotify event. Use of
XSGIvcLoadVideoFormatCombination may result in a
VideoFormatNotify event for each channel in the multi-
channel system.
SEE ALSO
XSGIvc, XSGIvcLoadVideoFormat,
XSGIvcLoadVideoFormatCombination,
XSGIvcQueryVideoScreenInfo, XSGIvcQueryMonitorName,
setmon(1G)
Page 11 (printed 7/20/06)
