visual_io(7I)
NAME
visual_io - Solaris VISUAL I/O control operations
SYNOPSIS
#include <sys/visual_io.h>
DESCRIPTION
The Solaris VISUAL environment defines a small set of
ioctl()s for controlling graphics and imaging devices.
One ioctl(), VIS_GETIDENTIFIER, is mandatory, and must be
implemented in device drivers for graphics devices using the
Solaris VISUAL environment. The VIS_GETIDENTIFIER ioctl() is
defined to return a device identifier from the device
driver. This identifier must be a uniquely-defined string.
Two other sets of ioctl()ls exist. One set supports mouse
tracking via hardware cursor operations. These are
optional, but if a graphics device has hardware cursor sup-
port and implements these ioctl()s the mouse tracking per-
formance will be improved.
The other set supports the device being the system console
device. These are optional, but if a graphics device is to
be used as the system console device, it must implement
these ioctl()s.
IOCTLS
VIS_GETIDENTIFIER
This ioctl() returns an identifier string to uniquely
identify a device used in the Solaris VISUAL environ-
ment. This is a mandatory ioctl() and must return a
unique string. We suggest that the name be formed as
<companysymbol><devicetype>. For example, the cgsix
driver returns SUNWcg6.
VIS_GETIDENTIFIER takes a vis_identifier structure as
its parameter. This structure has the form:
#define VIS_MAXNAMELEN 128
struct vis_identifier {
char name[VIS_MAXNAMELEN];
};
VIS_GETCURSOR
VIS_SETCURSOR
These ioctl()s fetch and set various cursor
attributes, using the vis_cursor structure.
struct vis_cursorpos {
short x; /* cursor x coordinate */
short y; /* cursor y coordinate */
};
struct vis_cursorcmap {
int version; /* version */
int reserved;
unsigned char *red; /* red color map elements */
unsigned char *green;/* green color map elements */
unsigned char *blue; /* blue color map elements */
};
#define VIS_CURSOR_SETCURSOR 0x01 /* set cursor */
#define VIS_CURSOR_SETPOSITION 0x02 /* set cursor position */
#define VIS_CURSOR_SETHOTSPOT 0x04 /* set cursor hot spot */
#define VIS_CURSOR_SETCOLORMAP 0x08 /* set cursor colormap */
#define VIS_CURSOR_SETSHAPE 0x10 /* set cursor shape */
#define VIS_CURSOR_SETALL (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | VIS_CURSOR_SETSHAPE)
struct vis_cursor {
short set; /* what to set */
short enable; /* cursor on/off */
struct vis_cursorpos pos; /* cursor position */
struct vis_cursorpos hot; /* cursor hot spot */
struct vis_cursorcmap cmap; /* color map info */
struct vis_cursorpos size; /* cursor bitmap size */
char *image; /* cursor image bits */
char *mask; /* cursor mask bits */
};
The vis_cursorcmap structure should contain
pointers to two elements, specifying the
red, green, and blue values for foreground
and background.
VIS_SETCURSORPOS
VIS_MOVECURSOR
These ioctl()s fetch and move the current
cursor position, using the vis_cursorpos
structure.
Console optional ioctls
The following set of ioctl()s are used by graphics drivers
that are to be part of the system console device. All of
the ioctl()s must be implemented to be a console device.
In addition, if the system does not have a prom or the prom
goes away during boot, the special standalone ioctl()ls
(listed below) must also be implemented.
The coordinate system for the console device places 0,0 at
the upper left corner of the device, with rows increasing
toward the bottom of the device and columns increasing from
left to right.
VIS_PUTCMAP
VIS_GETCMAP
Set or get color map entries.
The argument is a pointer to a vis_cmap structure,
which contains the following fields:
struct vis_cmap {
int index;
int count;
uchar_t *red;
uchar_t *green;
uchar_t *blue;
}
index is the starting index in the color map where you
want to start setting or getting color map entries.
count is the number of color map entries to set or
get. It also is the size of the red, green, and blue
color arrays.
*red, *green, and *blue are pointers to unsigned
character arrays which contain the color map info
to set or where the color map info is placed on a
get.
VIS_DEVINIT
Initializes the graphics driver as a console
device.
The argument is a pointer to a vis_devinit
structure.
The graphics driver is expected to allocate any
local state information needed to be a console
device and fill in this structure.
struct vis_devinit {
int version;
screen_size_t width;
screen_size_t height;
screen_size_t linebytes;
unit_t size;
int depth;
short mode;
};
version is the version of this structure and
should be set to VIS_CONS_REV.
width and height are the width and height of the
device. If mode (see below) is VIS_TEXT then
width and height are the number of characters
wide and high of the device. If mode is
VIS_PIXEL then width and height are the number
of pixels wide and high of the device.
linebytes is the number of bytes per line of the
device.
size is the total size of the device in pixels.
depth is the pixel depth it bits of the device.
Currently supported depths are: 1, 4, 8 and 24.
mode is the mode of the device. One of
VIS_PIXEL (data to be displayed is in bit-
map format) or VIS_TEXT (data to be
displayed is in ascii format).
VIS_DEVFINI
Tells the graphics driver that it is no
longer the system console device. There is
no argument to this ioctl(). The driver
is expected to free any locally kept state
information related to the console.
VIS_CONS_MODE_CHANGE
Tells the graphics driver that the frame-
buffer resolution has been reset by the
user program. The framebuffer is expected
to reload any state information that it is
keeping.
The argument to this ioctl() is private to
the user program and the device driver.
That is, the user program may wish to
directly change the framebuffer mode and
then just use this ioctl() to notify the
graphics driver or it may pass mode change
information along to the graphics driver
and have it do the mode change.
VIS_CONSCURSOR
Describes the size and placement of the
cursor on the screen. The graphics driver
is expected to display or hide the cursor
at the indicated position.
The argument is a pointer to a
vis_conscursor structure which contains
the following fields:
struct vis_conscursor {
int version;
screen_pos_t row;
screen_pos_t col;
screen_size_t width;
screen_size_t height
color_t fg_color;
color_t bg_color;
short action;
};
version is set to VIS_CURSOR_VERSION and
should be check by the driver. If the
version does not match, the driver should
reject this ioctl().
row and col are the first row and column
(upper left corner of the cursor).
width and height are the width and height
of the cursor.
If mode in the VIS_DEVINIT ioctl() was set
to VIS_PIXEL, then col, row, width and
height are in pixels. If mode in the
VIS_DEVINIT ioctl() was set to VIS_TEXT,
then col, row, width and height are in
characters.
fg_color and bg_color are the foreground
and background color map indexes to use
when the action (see below) is set to
VIS_DISPLAY_CURSOR.
action is whether to display or hide
the cursor.
It is set to one of: VIS_HIDE_CURSOR
or VIS_DISPLAY_CURSOR.
VIS_CONSDISPLAY
Display data on the graphics device.
The graphics driver is expected to
display the data contained in the
vis_display structure at the speci-
fied position on the console.
The vis_display structure contains
the following fields:
struct vis_display {
int version;
screen_pos_t row;
screen_pos_t col;
screen_size_t width;
screen_size_t height;
uchar_t *data;
color_t fg_color;
color_t bg_color;
};
version is set to
VIS_DISPLAY_VERSION and should be
check by the driver. If the version
does not match, the driver should
reject this ioctl().
row and col specify the starting row
and column to display the data at.
If mode in the VIS_DEVINIT ioctl()
was set to VIS_TEXT, row and col
are defined to be a character offset
from the starting position of the
console device. If mode in the
VIS_DEVINIT ioctl() was set to
VIS_PIXEL, row and col are defined
to be a pixel offset from the start-
ing position of the console device.
width and height specify the size of
the data to be displayed. If mode
in the VIS_DEVINIT ioctl() was set
to VIS_TEXT, width and height
define the size of data as a rec-
tangle that is width characters wide
and height characters high. If mode
in the VIS_DEVINIT ioctl() was set
to VIS_PIXEL, width and height
define the size of data as a
rectangle that is width pixels wide
and height pixels high.
*data is a pointer to the data to be
displayed on the console device. If
mode in the VIS_DEVINIT ioctl() was
set to VIS_TEXT, data is an array of
ASCII characters to be displayed on
the console device. The driver must
break these characters up appropri-
ately and display it in the retan-
gle defined by row, col, width, and
height. If mode in the VIS_DEVINIT
ioctl() was set to VIS_PIXEL, data
is an array of bitmap data to be
displayed on the console device.
The driver must break this data up
appropriately and display it in the
retangle defined by row, col,
width, and height.
The fg_color and bg_color
fields define the foreground
and background color map
indexes to use when displaying
the data. fb_color is used for
"on" pixels and bg_color is
used for "off" pixels.
VIS_CONSCOPY
Copy data from one location on
the device to another. The
driver is expected to copy the
specified data. The source
data should not be modified.
Any modifications to the
source data should be as a
side effect of the copy desti-
nation overlapping the copy
source.
The argument is a pointer to a
vis_copy structure which con-
tains the following fields:
struct vis_copy {
int version
screen_pos_t s_row;
screen_pos_t s_col;
screen_pos_t e_row;
screen_pos_t e_col;
screen_pos_t t_row;
screen_pos_t t_col;
short direction;
};
version is set to
VIS_COPY_VERSION and should be
check by the driver. If the
version does not match, the
driver should reject this
ioctl().
s_row, s_col, e_row, and e_col
define the source rectangle of
the copy. s_row and s_col are
the upper left corner of the
source rectangle. e_row and
e_col are the lower right
corner of the source rectan-
gle. If mode in the
VIS_DEVINIT ioctl() was set to
VIS_TEXT, s_row, s_col, e_row,
and e_col are defined to be
character offsets from the
starting position of the con-
sole device. If mode in the
VIS_DEVINIT ioctl() was set to
VIS_PIXEL, s_row, s_col,
e_row, and e_col are defined
to be pixel offsets from the
starting position of the con-
sole device.
t_row and t_col define the
upper left corner of the des-
tination rectangle of the
copy. The entire rectangle is
copied to this location. If
mode in the VIS_DEVINIT
ioctl() was set to VIS_TEXT,
t_row, and t_col are defined
to be character offsets from
the starting position of the
console device. If mode in
the VIS_DEVINIT ioctl() was
set to VIS_PIXEL, t_row, and
t_col are defined to be pixel
offsets from the starting
position of the console dev-
ice.
direction specifies which
way to do the copy. If
direction is
VIS_COPY_FORWARD the
graphics driver should
copy data from position
(s_row, s_col) in the
source rectangle to posi-
tion (t_row, t_col) in
the destination rectan-
gle. If direction is
VIS_COPY_BACKWARDS the
graphics driver should
copy data from position
(e_row, e_col) in the
source rectangle to posi-
tion (t_row+(e_row-
s_row), t_col+(e_col-
s_col)), in the destina-
tion rectangle.
The next set of console
ioctl()s are used on systems
which don't have a prom. Nor-
mally, standalones use the
system prom to display charac-
ters on the system console
device. On systems without a
prom, standalones use the ker-
nel drivers to display charac-
ters on the system console
device. When implementing
these ioctl()s, you can not
use any of the locking primi-
tives or the copy routines
from the DDI. Furthermore
other DDI services may or may
not work and should be
avoided.
VIS_STAND_CONSCURSOR
Should perform the same
tasks as VIS_CONSCURSOR
except that it must fol-
low the above restric-
tions. It takes in as
an argument a vis_cursor
structure.
VIS_STAND_CONSDISPLAY
Should perform the same
tasks as VIS_CONSDISPLAY
except that it must fol-
low the above restric-
tions. It takes in as
an argument a
vis_display structure.
VIS_STAND_CONSCOPY
Should perform the same
tasks as VIS_CONSCOPY
except that it must fol-
low the above restric-
tions. It takes in as
an argument a vis_copy
structure.
Man(1) output converted with
man2html