XSGIvcListVideoFormats(3)
XSGIvcListVideoFormats, XSGIvcListVideoFormatCombinations, XSGIvcListVideoFormatsInCombination, XSGIvcLoadVideoFormat, XSGIvcLoadVideoFormatCombination, XSGIvcDisableChannel - Video Format Query and Load Functions
As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.
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, 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 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 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 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 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. 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: 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 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) #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 */ 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)