.if n .pH arch.screen @(#)screen	40.1
.ig
imaged dc 8/30/89
docformat -c -s4 -dqm4 fn
..
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.ds S) Shapes
.BK CH_Screen "\\*(bK"
.CH "The SCREEN Object" 10
.H 1 "Introduction"
.P
.nh
A screen object is associated with every device
used for rendering.
The screen object holds basic information about
the display device \(em where it begins in memory,
how many pixels wide, high, etc.
Many raster objects can be associated with a
single screen object.
.P
The screen object is internal to \*(S);
it is not documented in the
\f2Shapes Reference Manual\f1
as a user-level object.
.P
Shapes creates screens at initialization
(di/init.c) in order to make memory rasters
available,
and also when the user creates new rasters
(dd/rasScr.c).
Of course, if a screen for the requested device
already exists,
\*(S) does not create a new screen object.
.P
There can be many virtual devices associated with
a particular physical device.
For example, the physical device CG4 can be
broken down into virtual devices /dev/cgfour_ove
(overlay enable plane),
/dev/cgfour_ovl (overlay plane),
and /dev/cgfour_clr (color planes).
It is the virtual device name that is passed to
Create_Raster when a screen raster is made.
.P
\*(S) maintains a table of screen objects
representing all of the currently open virtual devices.
When a screen raster is created,
this table is searched to see if the virtual
device name requested has already been opened.
If not, then a new screen is created to represent
the virtual device and is added to this table.
At this time, the physical device is referenced
and opened if necessary.
.P
There is also a table of use counts for the
physical devices.
There is one count for each physical device in
the system.
It starts out at zero and is incremented when the
physical device is opened and each time the
physical device is again used by some virtual device.
.P
\*(S) maintains a unique definition for each
physical device it supports.
These numbers are defined in include/sh_scr_dev.h.
The physical device numbers (SCR_DEV_xxx)
define the allowable values for the
OBJ_CLASS_TYPE attribute of an object.
It is this attribute that controls the dispatch
table associated with the object
that defines its implementation.
There is the potential for a different
implementation of all \*(S) classes for each
physical device.
In practice, a great deal of the implementation
of each class is shared by all devices.
.P
.H 2 "Screen Attributes"
The screen attributes with capitalized names are
used by other \*(S) routines.
The names in small letters denote attributes only
used in the implementation of the screen object.
Screen attributes are defined in include/di/sh_SCR.ah.
.PC
Unsgn8   SCR_NAME[FB_NAME_SIZE];
Unsgn8   SCR_PHYS_DEV;
Unsgn8   SCR_VIRT_DEV;
Unsgn8   SCR_DEPTH;
Unsgn8   scr_depth_index;
Unsgn8   SCR_CMAP_SIZE;
Unsgn16  SCR_LINEBYTES;
Unsgn16  SCR_WIDTH;
Unsgn16  SCR_HEIGHT;
int      SCR_DEV_FD;
int      SCR_WIN_FD;
Unsgn32  SCR_MAX_PLANE_MASK;
Unsgn8   *SCR_RAS_START;
CMAP     SCR_CMAP_INDEX;
CMAP     SCR_CMAP_RGB;
RND_FUNC  *SCR_PATH_FUN;
RND_FUNC  *SCR_STROKE_FUN;
RND_FUNC  *SCR_FILL_FUN;
RND_FUNC  *SCR_COPY_FUN;
RND_FUNC  *SCR_GLYPH_FUN;
.SF
.H 2 SCR_NAME
.P
The name that the operating system will recognize
when opening the device.
.H 2 "SCR_PHYS_DEV, SCR_VIRT_DEV"
.P
Devices from the list of devices in file sh_scr_dev.h
(which must be updated when new devices are added).
This is how \*(S) differentiates one type of
device from another.
Usually there is only one SCR_PHYS_DEV type,
but with some devices
(like the Sun cg4 frame buffer),
there can be several SCR_VIRT_DEV types for a
single SCR_PHYS_DEV.
SCR_VIRT_DEV types generally mimic one or more
SCR_PHYS_DEV.
Each SCR_VIRT_DEV type will have a unique screen
object allocated for it even though they may all
be on the same physical device.
.H 2 SCR_DEPTH
.P
The bit depth of a pixel on this screen.
.H 2 scr_depth_index
.P
A unique pixel depth index.
The possible values are defined in /include/sh_RAS.h,
which currently includes RAS_DEPTH_1,
RAS_DEPTH_4,
RAS_DEPTH_8, and RAS_DEPTH_32.
This value is used in low-level rendering code to
distinguish between raster depths during
cross-depth rendering operations.
If you plan to add support for a new pixel depth,
you should define a new RAS_DEPTH_XX value.
Only code in the /dd directory and its
subdirectories must be altered to handle the new
depth value.
.H 2 SCR_CMAP_SIZE
.P
The maximum number of color map entries
available for this device.
.H 2 SCR_LINEBYTES
.P
The number of bytes (padded) per scanline on this device.
.H 2 SCR_WIDTH
.P
The number of pixels per scanline on this device.
.H 2 SCR_HEIGHT
.P
The number of scanlines on this device.
.H 2 SCR_DEV_FD
.P
The location of the UNIX file descriptor is saved
for the device while it is open.
.H 2 SCR_WIN_FD
.P
The location of the Sunview1 window file
descriptor is saved for the device
(this is used for Sunview1 backward compatibility).
.H 2 SCR_MAX_PLANE_MASK
.P
The maximum plane enable value that is valid on
pixels in this screen object.
It is used when determining whether code that
supports plane enable masks should be used during
rendering.
Currently, the only pixel depth where this value
is different from the depth is for 32 bit deep pixels.
.H 2 SCR_RAS_START
.P
The address of the first pixel in the frame
buffer when accessing it as a dumb frame buffer.
Currently, \*(S) assumes that when it needs to
read or write pixels on the screen to support
some function not supported by hardware it can
get to them using this address,
and that complete pixels
(all bits in SCR_DEPTH)
can be accessed via this method
(especially when reading pixels).
.H 2 SCR_CMAP_INDEX
.P
The indexed color map associated with
the screen object when one exists.
.H 2 SCR_CMAP_RGB
.P
The RGB color map associated with the screen
object when one exists.
.H 2 SCR_PATH_FUN
.P
The dispatch vector for all Shapes path operators
for this device.
Since path operators do not render pixels
directly on dumb frame buffers,
this dispatch vector needs no device specific
support for a dumb frame buffer port.
The generic dispatch vector can be used here
(sh_fb_path_fun).
.H 2 SCR_STROKE_FUN
.P
The dispatch vector for the vector and
curve rendering functions for the device.
This dispatch vector should be initialized to
point to the device-specific dispatch table
stroke_fun[] in the xxxRas.c file for your device.
.H 2 SCR_FILL_FUN
.P
The dispatch vector for the area fill rendering
functions for the device.
This dispatch vector should be initialized to
point to a device-specific dispatch table
fill_fun[] in the xxxRas.c file for your device.
.H 2 SCR_COPY_FUN
.P
The dispatch vector for the raster copy
rendering functions for the device.
This dispatch vector should be initialized to
point to a device-specific dispatch table
copy_fun[] in the xxxRas.c file for your device.
.H 2 SCR_GLYPH_FUN
.P
The dispatch vector for the glyph rendering
functions for the device.
This dispatch vector should be initialized to
point to a device-specific dispatch table
glyph_fun[] in the xxxRas.c file for your device.
.H 2 "Screen Operators"
.P
This section describes the screen operators.
Because the screen object is internal to \*(S),
these operators are not covered in the
\f2Shapes Reference Manual\f1.
They are defined in include/di/sh_SCR.h.
.H 2 Create_Screen
.P
Creates the screen object and tries to open the
display device by calling the function pointed to
by fb_open_function.
If the display device is successfully opened,
the name of the new screen object is added to the
Scr_Phys table.
.P
The logic for this call is as follows:
.AL
.LI
Init_Raster evaluates the need to create a new
screen for the raster by searching sh_Scr_Virt.
.LI
If sh_Scr_Virt does not already have a screen
representing this virtual device,
Init_Raster calls Create_Screen.
.LI
Create_Screen allocates memory for the new screen
by calling Create_Obj().
.LI
Init_Screen is invoked to initialize the screen.
It searches sh_Scr_Dev for the virtual device name and,
if it finds an entry that matches,
it calls the associate device open routine.
Otherwise it calls the more generic
sysVvga_open
(in init.c).
The device open call initialize the values in the
screen object.
.LI
For sysVvga_open
an additional init for each different kind of
framebuffer is required.
This init is usually found in the xxxRas.c files
(e.g., Bw2Ras.c).
This function initializes the dispatch table for
the screen (SCR_RND_FUN SCR_PATH_FUN)
as well as putting in a request to the operating
system to map in the framebuffer memory.
.LE
.P
.H 2 Destroy_Screen
.P
Closes the device if there are no other objects
referencing the screen.
.P
.H 2 Set_Screen
.P
Set_Screen is implemented through macros.
You can only set SCR_CMAP_INDEX,
SCR_CMAP_RGB, and SCR_WIN_FD.
.P	
.H 2 Close_Screen
.P
Close_Screen puts in a request to the operating
system to disengage \*(S) and the screen device.
.P
.H 2 Attach_Screen
.P
When a raster is created,
it must be associated with a screen object.
Attach_Screen increases the reference
count of the screen and initializes the raster
with the screen object.
.H 2 "Related Routines and Tables"
.P
If you want to open a framebuffer and your device
is not standard,
you will need to write an unique routine for
opening it and then dispatch to this routine by
properly initializing the sh_Scr_Dev data structure.
.P
The openvt function (in init.c) maps the
framebuffer memory into the CPU memory space.
It is dependent on the operating system.
.H 2 "Data Structures"
This section discusses the global data structures
used in creating and manipulating screen objects.
.H 2 "sh_Scr_Dev[]"
.P
Describes where to find the framebuffer open routine.
If it is not explicitly described,
this routine defaults to sh_fb_open().
Currently, sh_Scr_Dev is initialized in init.c to:
.P
.PC
SCRDEV sh_Scr_Dev[] = {
       {char * ) NULL, sysVvga_open},
       };
.SF
.H 2 "Scr_Phys[]"
.P
Physical screen table (found in dd/scrRas.c).
It is indexed by the physical device number, SCR_DEV_xxx.
The table contains a reference count for each
physical device that indicates the number of
times the physical device has been used.
The values are changed by operations
Create_Screen and Destroy_Screen.
When this use count goes to zero,
the device is closed.
.H 2 "sh_Scr_Virt[]"
.P
Virtual screen table (found in dd/init.c).
The table contains a screen object for each
virtual device that has been opened.
All rasters are associated with a specific
virtual device.
The first few entries in sh_Scr_Virt are the
virtual devices for memory rasters.
They are indexed by their physical device offset
SCR_DEV_MEMx and are created on startup.
Subsequent sh_Scr_Virt entries are created when
screen rasters are made.
These are added to the table in the order they
are asked for.
They are destroyed by Destroy_Raster when all the
rasters using that screen have been removed.
At this time, the physical device is closed.
