.\"	$OpenBSD: grf.4,v 1.13 2003/09/04 22:14:42 jmc Exp $
.\"
.\" Copyright (c) 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Systems Programming Group of the University of Utah Computer
.\" Science Department.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     from: @(#)grf.4	8.1 (Berkeley) 6/9/93
.\"
.Dd June 9, 1993
.Dt GRF 4 hp300
.Os
.Sh NAME
.Nm grf
.Nd
.Tn HP
graphics frame buffer device interface
.Sh SYNOPSIS
.Cd "grf* at dvbox?"
.Cd "grf* at gbox?"
.Cd "grf* at hyper?"
.Cd "grf* at rbox?"
.Cd "grf* at topcat?"
.Cd ""
.Cd "ite* at grf?"
.Sh DESCRIPTION
This is a generic description of the frame buffer device interface.
.Pp
The devices to which this applies are the 98544, 98545 and 98547
Topcat graphics cards (also known as
.Tn HP300H
devices),
the 98548, 98549 and 98550
Catseye graphics cards,
the A1416A
Kathmandu graphics cards,
the 98700
Gatorbox graphics box,
the 98720
Renaissance graphics box,
the 98730
DaVinci graphics box,
and the A1096A
Hyperion graphics cards.
.Pp
The basic programming of the
.Nm grf Ns ?\&
devices involves opening the device
file, mapping the control registers and frame buffer addresses into user
space, and then manipulating the device as the application requires.
The address mapping is controlled by an
.Xr ioctl 2
call to map the device into user space, and an unmap call when finished.
.Pp
The ioctls supported by
.Ox
are:
.Bl -tag -width GRFIOCGINFO
.It Dv GRFIOCGINFO
Get Graphics Info
.Pp
Get info about device, setting the entries in the
.Em grfinfo
structure, as defined in
.Aq Pa machine/grfioctl.h :
.Bd -literal
struct	grfinfo {
	int	gd_id;		/* HP-UX identifier */
	caddr_t	gd_regaddr;	/* control registers physaddr */
	int	gd_regsize;	/* control registers size */
	caddr_t	gd_fbaddr;	/* frame buffer physaddr */
	int	gd_fbsize;	/* frame buffer size */
	short	gd_colors;	/* number of colors */
	short	gd_planes;	/* number of planes */
/* new stuff */
	int	gd_fbwidth;	/* frame buffer width */
	int	gd_fbheight;	/* frame buffer height */
	int	gd_dwidth;	/* displayed part width */
	int	gd_dheight;	/* displayed part height */
	int	gd_pad[6];	/* for future expansion */
};
.Ed
.It Dv GRFIOCON
Graphics On
.Pp
Turn graphics on by enabling
.Tn CRT
output.
The screen will come on, displaying whatever is in the frame buffer, using
whatever colormap is in place.
.It Dv GRFIOCOFF
Graphics Off
.Pp
Turn graphics off by disabling output to the
.Tn CRT .
The frame buffer contents
are not affected.
.It Dv GRFIOCMAP
Map Device to user space
.Pp
Map in control registers and frame buffer space.
Once the device file is mapped, the frame buffer memory and registers
are accessible.
.It Dv GRFIOCUNMAP
Unmap Device
.Pp
Unmap control registers and frame buffer space.
.El
.Sh FILES
.Bl -tag -width /dev/XXXX -compact
.It Pa /dev/grf?
.Ox
interface special files
.El
.Sh EXAMPLES
This short code fragment is an example of opening some graphics device and
mapping in the control and frame buffer space:
.Bd -literal
#define GRF_DEV <some_graphics_device>  /* /dev/grfN */

struct fbstruct *regs;  /*  fbstruct = gboxfb, rboxfb, etc. */
u_char *Addr, frame_buffer;
struct grfinfo gi;
int disp_fd;

disp_fd = open(GRF_DEV, O_WRONLY);
if (ioctl(disp_fd, GRFIOCGINFO, &gi) < 0) return -1;
ioctl(disp_fd, GRFIOCON, 0);

if (ioctl(disp_fd, GRFIOCMAP, &Addr) < 0) {
	ioctl(disp_fd, GRFIOCOFF, 0);
	return -1;
}
regs = (fbstruct *)Addr;               /* Control Registers   */
frame_buffer = (u_char *)Addr + gi.gd_regsize; /* Frame buffer mem */
.Ed
.Sh DIAGNOSTICS
None under
.Ox .
.Pp
.Tn HP-UX
The
.Tn CE.utilities/Crtadjust
programs, running in
.Tn HP-UX
compatibility mode,
can be used for each specific device.
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr cons 4 ,
.Xr dvbox 4 ,
.Xr gbox 4 ,
.Xr hil 4 ,
.Xr hyper 4 ,
.Xr intro 4 ,
.Xr ite 4 ,
.Xr rbox 4 ,
.Xr topcat 4