share/man/man4/man4.hp300/grf.4

   1 .\"     $NetBSD: grf.4,v 1.8 2002/02/13 08:17:57 ross Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the Systems Programming Group of the University of Utah Computer
   8 .\" Science Department.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     from: @(#)grf.4 8.1 (Berkeley) 6/9/93
  35 .\"
  36 .Dd September 10, 2001
  37 .Dt GRF 4 hp300
  38 .Os
  39 .Sh NAME
  40 .Nm grf
  41 .Nd
  42 .Tn HP
  43 graphics frame buffer device interface
  44 .Sh SYNOPSIS
  45 .Cd "grf* at dvbox?"
  46 .Cd "grf* at gbox?"
  47 .Cd "grf* at hyper?"
  48 .Cd "grf* at rbox?"
  49 .Cd "grf* at topcat?"
  50 .Sh DESCRIPTION
  51 This is a generic description of the frame buffer device interface.
  52 The devices to which this applies are the 98544, 98545 and 98547
  53 Topcat display cards (also known as
  54 .Tn HP300H
  55 devices),
  56 the 98548, 98549 and 98550
  57 Catseye display cards,
  58 the 98700
  59 Gatorbox graphics box,
  60 the 98720
  61 Renaissance graphics box,
  62 and the 98730
  63 DaVinci graphics box.
  64 .Pp
  65 Use of the devices can be effectively approached from two directions.
  66 The first is through
  67 .Tn HP-UX
  68 .Em Starbase
  69 routines, the second is by direct control in the
  70 .Bx
  71 environment.
  72 In order to use the Starbase libraries,
  73 code must be compiled in an
  74 .Tn HP-UX
  75 environment, either by doing so on an
  76 .Tn HP-UX
  77 machine and transferring the binaries to the
  78 .Bx
  79 machine, or by compilation
  80 with the use of the
  81 .Ic hpux
  82 command.
  83 Applications using Starbase libraries have been run successfully
  84 on
  85 .Bx
  86 machines using both of these compilation techniques.
  87 .Pp
  88 Direct compilation,
  89 such as that used for the X Window System servers, has also been successful.
  90 Examples of some frame buffer operations can be found in
  91 the device dependent X Window system sources, for example the
  92 .Pa /usr/src/new/X/libhp.fb
  93 directory.  These files contain examples of device dependent color map
  94 initialization, frame buffer operations, bit moving routines etc.
  95 .Pp
  96 The basic programming of the
  97 .Nm grf Ns ?
  98 devices involves opening the device
  99 file, mapping the control registers and frame buffer addresses into user
 100 space, and then manipulating the device as the application requires.
 101 The address mapping is controlled by an
 102 .Xr ioctl 2
 103 call to map the device into user space, and an unmap call when finished.
 104 The ioctls supported by
 105 .Bx
 106 are:
 107 .Bl -tag -width indent
 108 .It Dv GRFIOCGINFO
 109 Get Graphics Info
 110 .Pp
 111 Get info about device, setting the entries in the
 112 .Em grfinfo
 113 structure, as defined in \*[Lt]hpdev/grfioctl.h\*[Gt]:
 114 .Bd -literal
 115 struct  grfinfo {
 116         int     gd_id;          /* HPUX identifier */
 117         caddr_t gd_regaddr;     /* control registers physaddr */
 118         int     gd_regsize;     /* control registers size */
 119         caddr_t gd_fbaddr;      /* frame buffer physaddr */
 120         int     gd_fbsize;      /* frame buffer size */
 121         short   gd_colors;      /* number of colors */
 122         short   gd_planes;      /* number of planes */
 123 /* new stuff */
 124         int     gd_fbwidth;     /* frame buffer width */
 125         int     gd_fbheight;    /* frame buffer height */
 126         int     gd_dwidth;      /* displayed part width */
 127         int     gd_dheight;     /* displayed part height */
 128         int     gd_pad[6];      /* for future expansion */
 129 };
 130 .Ed
 131 .It Dv GRFIOCON
 132 Graphics On
 133 .Pp
 134 Turn graphics on by enabling
 135 .Tn CRT
 136 output.  The screen will come on, displaying
 137 whatever is in the frame buffer, using whatever colormap is in place.
 138 .It Dv GRFIOCOFF
 139 Graphics Off
 140 .Pp
 141 Turn graphics off by disabling output to the
 142 .Tn CRT .
 143 The frame buffer contents
 144 are not affected.
 145 .It Dv GRFIOCMAP
 146 Map Device to user space
 147 .Pp
 148 Map in control registers and framebuffer space. Once the device file is
 149 mapped, the frame buffer structure is accessible.
 150 .It Dv GRFIOCUNMAP
 151 Unmap Device
 152 .Pp
 153 Unmap control registers and framebuffer space.
 154 .El
 155 .Pp
 156 For further information about the use of ioctl see the man page.
 157 .Sh FILES
 158 .Bl -tag -width /dev/*crt*? -compact
 159 .It Pa /dev/grf?
 160 .Bx
 161 interface special files
 162 .It Pa /dev/*crt*
 163 .Tn HP-UX
 164 .Em starbase
 165 interface special files
 166 .El
 167 .Sh EXAMPLES
 168 This short code fragment is an example of opening some graphics device and
 169 mapping in the control and frame buffer space:
 170 .Bd -literal
 171 #define GRF_DEV \*[Lt]some_graphics_device\*[Gt]  /* /dev/grfN */
 172 {
 173         struct fbstruct *regs;  /*  fbstruct = gboxfb, rboxfb, etc. */
 174         u_char *Addr, frame_buffer;
 175         struct grfinfo gi;
 176         int disp_fd;
 177
 178         disp_fd = open(GRF_DEV,1);
 179         if (ioctl (disp_fd, GRFIOCGINFO, \*[Am]gi) \*[Lt] 0) return -1;
 180         (void) ioctl (disp_fd, GRFIOCON, 0);
 181
 182         Addr = (u_char *) 0;
 183         if (ioctl (disp_fd, GRFIOCMAP, \*[Am]Addr) \*[Lt] 0) {
 184                 (void) ioctl (disp_fd, GRFIOCOFF, 0);
 185                 return -1;
 186         }
 187         regs = (fbstruct *) Addr;               /* Control Registers   */
 188         frame_buffer = (u_char *) Addr + gi.gd_regsize; /* Frame buffer mem */
 189 }
 190 .Ed
 191 .Sh DIAGNOSTICS
 192 None under
 193 .Bx .
 194 .Tn HP-UX
 195 The
 196 .Tn CE.utilities/Crtadjust
 197 programs must be used for each specific device.
 198 .Sh ERRORS
 199 .Bl -tag -width [EINVAL]
 200 .It Bq Er ENODEV
 201 no such device.
 202 .It Bq Er EBUSY
 203 Another process has the device open.
 204 .It Bq Er EINVAL
 205 Invalid ioctl specification.
 206 .El
 207 .Sh SEE ALSO
 208 .Xr ioctl 2 ,
 209 .Xr dvbox 4 ,
 210 .Xr gbox 4 ,
 211 .Xr hil 4 ,
 212 .Xr hyper 4 ,
 213 .Xr rbox 4 ,
 214 .Xr topcat 4