ircombine(1G) ircombine(1G) NAME ircombine - Create, modify, query, load and save video format combinations SYNOPSIS /usr/gfx/ircombine [destination] [source] [options] DESCRIPTION ircombine creates and operates on video format combinations, descriptions of raster sizes and timings to be used on video outputs, as well as the configuration of the underlying frame buffer. The resulting combination can be used as the current video configuration, stored as the default configuration to be used at system power-up or graphics initialization, or saved in a video format combination file. The combination can be created from scratch or by modifying the current or a saved combination. Ircombine requires write access to the /usr/gfx/ucode/KONA/dg4/cmb directory to download combinations. Users can change between pre-built combinations using the setmon(1g) command. ircombine subsumes the functionality of setmon(1G). Options -destination [active | eeprom | file <filename>] - This option specifies the destination of the video format combination. If this option is omitted, and no queries are specified, ircombine will bring up a graphical interface by default. active specifies that the combination will be loaded as the current, active video configuration, but not saved in the eeprom. This will temporarily change the video configuration, but the combination will not be used when graphics is initialized or the the system is powered up. A destination of active is only legal if the target machine is local. eeprom specifies that the combination will be saved in the eeprom and used as the default. The combination does not take effect immediately; it is only used the next time graphics is initialized or the system is powered up. To initialize graphics, use (/usr/gfx/stopgfx; /usr/gfx/startgfx) & file specifies that the combination will be saved in a video format combination file <filename>. <filename> is specified relative to the current working directory. -source [active | file <filename>] - This option controls the source of the combination to me modified, loaded, or queried. active and file are similar to the options to -destination. If the source is active, the destination must be active as well, and only the following parameters may be modified: cursorpriority, filtersize, gain, gamma, hphase, pedestal, schphase, sourceloc, sourcesize, vphase; in addition, if the source is active channels may be disabled, but not enabled. If -source is not specified, all parameters which are not specified take on their default values. -gui - Brings up a graphical interface with which to create video format combinations. If this option is specified in conjunction with other options which modify the combination, the other operations are performed first, and the gui may be used to make additional modifications. This option may not be specified with -destination. If no destination is specified, and no queries are made to the combination, the graphical interface is used by default. The following options modify the specified video format combination, or query parameters of the combination and return them on stdout. -global [parameter|parameter=value,...] - Modifies or queries the global attributes of the video format combination. This option is followed by a list of parameters or parameter assignments. If no assignment is made, the current setting of the parameter in the modified combination is queried and returned on stdout. Parameters may be specified multiple times in order to both set and query a parameter. Since commas delimit parameters in this list, they not used in value. The following parameters may be specified: gamma=<value> - Specifies the global output video gamma value for this combination. If the globalgamma parameter is ON, this gamma value is used for all channels in the combination. Valid values for gamma are floating point numbers in the range [0,20], and the default is 1.7. Setting this parameter modifies the gamma values on all components of the output. To modify the gamma value of a single component, use one of the options gammar, gammag, or gammab. globalgamma= [ON|OFF] - Specifies whether the global gamma value is used as the output video gamma for all channels in the combination. The DG4-2 display generator supports a single output gamma map, so globalgamma must be used with this target hardware. The DG4-8 supports sixteen gamma maps, so each channel may use its own unique gamma value. pixeldepth= [ DEEPEST | XS | S | M | L | XL ] - Specifies the size of the pixels to be used in the combination. If XS, S, M, L, or XL is specified, the combination will only be used with this size pixel, and will be invalid if the specified pixel size is not available. If DEEPEST is specified, the largest pixel size which can be supported by the hardware configuration will be chosen at the time the combination is loaded. When the combination is validated, ircombine will report the pixel size which would be chosen for the given hardware configuration. size=XxY - Specifies the size of the frame buffer in pixels. The y-size must be a multiple of 2. The default is either 1280x1024 or the minimum legal bounding rectangle of the specified combination, whichever is larger. syncformat=<name> - For external sync, specifies the name of the video format file which describes the format to which the video subsystem will lock. If you do not specify an input genlock format, the video format of the combination's lowest numbered channel with a valid sync signal will be used. syncsource= [ INTERNAL | EXTERNAL | LOOPBACK_CH1 ] - Specifies whether the default genlock source will be internal, external, or loopbacked via an external cable from the channel 1 output. textport=<channel number> - Specifies the channel to be used as the textport output. This is the channel on which the PROM monitor is displayed. See prom(1M). This channel must be a valid channel in the combination. By default, the combination's lowest numbered channel is used. -channel <channel> [parameter|parameter=value,...] - Modifies or queries the attributes associated with the specified channel of the video format combination. <channel> may be a number in the range 0-7 to specify the corresponding video channel, encoder to specify the encoder channel, sirius to specify the Sirius option board (if it exists), dplex to specify the dplex board (if it exists), tvo to specify the tvo board (if it exists), hdgvo to specify the tvo board combined with vbob acting as hdgvo (if it exists) dvp to specify the digital video port board (if it exists), or gvo to specify the 601 serial digital video out board (if it exists). The -channel option may be used multiple times on a single command line to specify different channels of the video format combination. The assignment of parameters is similar in operation to -b. The following parameters may be specified: alpha= [ON|OFF] - Specifies that this channel should produce the alpha component of the pixels rather than RGB values. This must be used in conjunction with the RGBA10 pixel format, and produces the alpha component on the blue component of the output. When you use this option, gamma correction is disabled for the channel. colorspace=[ REC709_10 | REC709_8 | CCIR601_10 | CCIR601_8 | REC240_10 | REC240_8 | RGBA_4444 ] - Specifies the colorspace to be output by the HDGVO channel. In HDGVO, the RGB pixels from the framebuffer are converted into one of 3 colorspaces, at either 8 or 10 bits per component. The three colorspaces are REC 709, CCIR601, and REC240. The default colorspace is REC 709 at 10 bits per component. This setting does not work for channels other than HDGVO. cursorpriority=value - Specifies the priority of this channel for cursor drawing. This priority is used to determine which channel displays the cursor in a region in which the input rectangles of two or more channels overlap. Numbers range from 0 to 255, with lower numbers indicating higher priority. If the cursor enters a region shared by two channels of equal cursor priority, the channel which last displayed the cursor retains it. If the cursor did not previously appear in either of the contending channels, the channel with the lower channel number displays the cursor. delete - Specifies that the channel should be deleted from the combination. This parameter does not need to be given an assignment. dither= [ON|OFF] - Specifies whether or not the output of this channel is to be dithered. If dither is not selected, and the frame buffer color representation has more precision than the the video format, i.e., 12-bit RGB pixels in the frame buffer with RGB10 pixel format for video, the colors will be truncated. If dither is selected, a fixed pattern of noise will be added to the colors before they are truncated to reduce the perceptible artifacts introduced by truncation. By default, dithering is OFF. enable= [ON|OFF] - Specifies whether this channel should be enabled in the combination. If a channel is disabled, but not deleted, the definition of the channel is stored in the combination, but no output is generated, and no bandwidth is consumed for the channel. If any parameters are specified for a channel, it is enabled by default; all other channels are disabled by default. filtersize=XxY - Specifies the size of the filters used when the channel resizes the source pixels to the channel. Values for the x-filter are in the range [1,13], for the y-filter [1,7]. format=<format name> - Specifies the name of the video format to be used on this channel. For the encoder channel, the only valid values are NTSC and PAL, corresponding to the 640x486_30i and 768x576_25i formats. For Sirius, the valid values are 525, 625, CCIR601_525, and CCIR601_625, corresponding to the 646x486_30i, 768x576_25i, CCIR601_525 (720x485_25i), and CCIR601_625 (720x576_25i) formats, respectively. For GVO, the valid values are CCIR601_525_DGO, and CCIR601_625_DGO. The default format for the encoder is NTSC. The default for Sirius is 525. The default for GVO is CCIR601_525_DGO. The default format for all other channels is 1280x1024_60. gain=<value> - Specifies the default output video gain for this channel. The valid range is [0,10], and the default is 1. This value will be coerced to the closest gain which is physically realizable on the output channel. Thus, if the gain is set and subsequently queried, the input and returned values may not be the same. gamma=<value> - Specifies the output video gamma value for this channel. Valid values for gamma are floating point numbers in the range [0,20], and the default is 1.7. Setting this parameter modifies the gamma values on all components of the output channel. To modify gamma value on a single component, use one of the options gammar, gammag, or gammab. hphase=<value> - Specifies the default horizontal phase value for this channel. This setting applies only if the channel is genlocked to external sync. Positive values delay the genlocked video channel with respect to external sync, and negative values advance it. <value> is a floating point number. The default is 0. maxsize=WxH - Specifies the maximum size of the input region of the frame buffer. This places a limit on the bandwidth requirements of the channel, and is used in validating the video format combination. See also the sourcesize and minsize parameters. minsize=WxH - Specifies the minimum size of the input region of the frame buffer. If minsize is set equal to maxsize, the source rectangle cannot be rescaled. See also the sourcesize and maxsize parameters. panstep=[ LOCKED | PIXEL | TILE ]x[ LOCKED | PIXEL ] - Specifies the resolution with which the input window of the channel may be panned in x and y while the combination is active. This parameter does not affect the initial placement of the channel's source region. LOCKED indicates that the source rectangle cannot be be moved in the corresponding direction. PIXEL indicates that the window can be panned to any pixel location. TILE for the x resolution indicates that the x-coordinate of the window can only be moved in 160 pixel increments, corresponding to one frame buffer tile. This is used to decrease the bandwidth requirement of a video format combination. Because pixels are fetched from the frame buffer in 160 pixel tiles, if the input window is not aligned to these blocks, more pixels may need to be fetched that are actually used in the output. The default is TILExPIXEL. pedestal= [OFF|ON] - Enables pedestal (also known as setup), an artificial black level voltage, for this output. By default, setup is disabled. pixelformat=[ RGB10 | RGBA10 | RGB12 | Z | FS ] - Specifies the output pixel format for this channel. You may specify RGB10 to indicate 10-bit RGB (no alpha), RGBA10 to indicate 10-bit RGB (with alpha), RGB12 to indicate 12-bit RGB (no alpha), Z to indicate 24- bit Z component, or FS to indicate stereo field sequential. The output pixel format is unrelated to the underlying frame buffer organization. The default is RGB10. scan=[ PROGRESSIVE | INTERLEAVED | STACKED ] - Specifies the field layout of this channel in the frame buffer. PROGRESSIVE specifies sequential data fetching, in which each field draws from the entire source region of the channel. This is the default. INTERLEAVED specifies an interlaced output format, in which the lines of the fields are vertically interleaved in the frame buffer. STACKED specifies an interlaced output format, in which the lines of each field are contiguous; the lines of the first of n fields occupy the top nth of the frame buffer, the lines of the second field occupy the next nth, and so on. The default is either PROGRESSIVE or INTERLEAVED, according to the channel's video format. STACKED field layout allows you to reduce fill, rendering only the visible lines of each field of an interlaced format. schphase=<phase> - Specifies the subcarrier-to-H phase of the output of the channel. Note this value is useful only on the encoder channel. sourcechannel=<channel number> - Specifies the channel on which the current channel is dependent. If the source channel is the same as the current channel, the channel will run in independent mode. In dependent mode, a portion of the visible surface from the source channel is sent to this channel for video out. Only the encoder, Sirius, and GVO channels can operate in dependent mode. By default, this is the same as the channel number. sourceloc=w+h - Specifies the default origin of the source rectangle of this channel in the frame buffer. The location is specified in pixels, and is relative to the upper-left corner of the screen. The default origin is 0+0. sourcesize=XxY - Specifies the default size in pixels of the source rectangle of this channel in the frame buffer. This rectangle may be larger or smaller than the video format, but must be within the bounds specified by minsize and maxsize. This parameter is used for resizing pixels from the frame buffer for display. Setting it smaller or larger than the output size of the video format will cause the pixels to be magnified or minified. The default size is that of the video format for this channel. sync= [R | G | B | N] - Specifies which of the output components have sync enabled. Use a single letter or a combination of R (red component), G (green component), and B (blue component). N specifies sync on none of the components. Default is sync on green component. syncport= [COMPOSITE|HORIZONTAL] - Specifies the default setting for the output of the alternate sync port. Specifying COMPOSITE places composite sync on the sync port. Specifying HORIZONTAL places horizontal sync on the sync port. The default is COMPOSITE. synctrilevel= [ON|OFF] - Enables tri-level sync on the RGB outputs. The default is OFF. usegamma= [ON|OFF] - Specifies whether the gamma values specified for this channel should be used in generating the output video. If usegamma is OFF, the default gamma value will be used instead. The globalgamma global parameter overrides this option. vphase=<value> - Specifies the default vertical phase value for this channel. This setting applies only if the channel is genlocked to external sync. vphase ranges from 0 to the number of lines in the video format minus one. The default value is 0. Other options available with ircombine: -description<description> Specifies a string of up to 256 characters which describes the combination. If <description> contains any spaces, it should be enclosed in quotes. If the combination is written to a file, this string is included in the file; otherwise it has no effect. -inputfile<filename> - After command line options are exhausted, read additional input from filename. This file utilizes the same syntax as the command line, except that it may contain carriage returns between options or parameters. -printcommand - Generates a command line which would create the source combination. This command line is printed to stdout. If the destination option is specified, it will be reproduced on the generated command line. -target<displayname> - Specifies that the graphics system whose video format combination will be changed is a display other that specified by the DISPLAY environment variable. This option uses the same format as the -display toolkit option. Note that the -display option does not change the target display. The -target option may also be used to specify the pipe for which the combination is to be changed on systems with multiple graphics pipes. If the pipe number is not specified with this command line option, the pipe number is extracted from the DISPLAY environment variable. -validate[parameter=value,...] - Specifies the hardware configuration for which to validate that the video format combination can be supported. Any parameter which is not specified by this option defaults to the configuration of the target display, if it has InfiniteReality graphics. Otherwise, the defaults given below are used. The following parameters may be specified with this option: numrms=<count> - Specifies the number of raster managers available. The default is 1. gfxrev=<revision> - Specifies the version of graphics hardware. Valid types are ONYX_IR , ONYX2_IR , and ONYX2_R. The default is ONYX_IR. numchannels=<count> - Specifies the number of video channels available. The default is 2. channelrev=<revision> - Specifies the revision number of the video channels. The default is 0. optchanneltype=<type> - Specifies the type of the option channel. Valid types are NONE , SIRIUS, GVO, DPLEX, and DVP. The default is NONE. -verbose - Enables verbose mode. This causes a listing of the entire video format combination to be printed to stdout. STATUS On completion, ircombine returns a 0 if the combination was successfully created. If ircombine was unsuccessful, it returns a non-zero value. EXAMPLES ircombine -destination file 1280x1024_60.cmb \ -channel 0 format=1280x1024_60.vfo Creates a combination file 1280x1024_60.cmb with a single channel whose format is 1280x1024_60. ircombine -destination active \ -source file 1280x1024_60.cmb \ -channel 0 gain = 2 Loads the combination stored in 1280x1024_60.cmb as the current combination, and changes channel 0's gain to 2. ircombine -destination file 640x486_30i.cmb \ -global size=640x486 \ -channel 0 format=640x486_30i.cmb, scan=INTERLEAVED Creates a combination file 640x486_30i.cmb with a managed area of 640x486 pixels, a single channel with a 30Hz interleaved format, 640x486_30i, and whose field layout is INTERLEAVED. ircombine -destination eeprom \ -global size=640x480 \ -channel 0 format=640x480_120s.vfo Stores a combination in the eeprom with a managed area of 640x480 pixels, and a single channel with a 120Hz stereo format, 640x480_120s. ircombine -destination file 2@1280x1024_72.cmb \ -channel 0 format=1280x1024_72.vfo, sourceloc=0+0, panstep=LOCKEDxLOCKED \ -channel 1 format=1280x1024_72.vfo, sourceloc=1280+0, panstep=LOCKEDxLOCKED Creates a combination file 2@1280x1024_72.cmb with two channels whose formats are both 80x1024_72, and whose source regions are located side by side in the frame buffer, with their locations fixed. SEE ALSO setmon(1G), Xvc(3). Page 9