share/man/man9/rasops.9

   1 .\"     $NetBSD: rasops.9,v 1.10 2006/02/18 18:36:26 jmcneill Exp $
   2 .\"
   3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Gregory McGarry.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd October 7, 2001
  31 .Dt RASOPS 9
  32 .Os
  33 .Sh NAME
  34 .Nm rasops ,
  35 .Nm rasops_init ,
  36 .Nm rasops_reconfig
  37 .Nd raster display operations
  38 .Sh SYNOPSIS
  39 .In dev/wscons/wsdisplayvar.h
  40 .In dev/rasops/rasops.h
  41 .Ft int
  42 .Fn rasops_init "struct rasops_info *ri" "int wantrows" "int wantcols"
  43 .Ft int
  44 .Fn rasops_reconfig "struct rasops_info *ri" "int wantrows" "int wantcols"
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 subsystem is a set of raster operations for
  49 .Xr wscons 9 .
  50 .Pp
  51 The primary data type for using the raster operations is the
  52 .Em rasops_info
  53 structure in
  54 .Pa dev/rasops/rasops.h :
  55 .Bd -literal
  56 struct rasops_info {
  57
  58         /*
  59          * These must be filled in by the caller
  60          */
  61         int     ri_depth;       /* depth in bits */
  62         u_char  *ri_bits;       /* ptr to bits */
  63         int     ri_width;       /* width (pels) */
  64         int     ri_height;      /* height (pels) */
  65         int     ri_stride;      /* stride in bytes */
  66
  67         /*
  68          * If you want shadow framebuffer support, point ri_hwbits
  69          * to the real framebuffer, and ri_bits to the shadow framebuffer
  70          */
  71         u_char  *ri_hwbits;
  72
  73         /*
  74          * These can optionally be left zeroed out. If you fill ri_font,
  75          * but aren't using wsfont, set ri_wsfcookie to -1.
  76          */
  77         struct  wsdisplay_font *ri_font;
  78         int     ri_wsfcookie;   /* wsfont cookie */
  79         void    *ri_hw;         /* driver private data */
  80         int     ri_crow;        /* cursor row */
  81         int     ri_ccol;        /* cursor column */
  82         int     ri_flg;         /* various operational flags */
  83
  84         /*
  85          * These are optional and will default if zero. Meaningless
  86          * on depths other than 15, 16, 24 and 32 bits per pel. On
  87          * 24 bit displays, ri_{r,g,b}num must be 8.
  88          */
  89         u_char  ri_rnum;        /* number of bits for red */
  90         u_char  ri_gnum;        /* number of bits for green */
  91         u_char  ri_bnum;        /* number of bits for blue */
  92         u_char  ri_rpos;        /* which bit red starts at */
  93         u_char  ri_gpos;        /* which bit green starts at */
  94         u_char  ri_bpos;        /* which bit blue starts at */
  95
  96         /*
  97          * These are filled in by rasops_init()
  98          */
  99         int     ri_emuwidth;    /* width we actually care about */
 100         int     ri_emuheight;   /* height we actually care about */
 101         int     ri_emustride;   /* bytes per row we actually care about */
 102         int     ri_rows;        /* number of rows (characters) */
 103         int     ri_cols;        /* number of columns (characters) */
 104         int     ri_delta;       /* row delta in bytes */
 105         int     ri_pelbytes;    /* bytes per pel (may be zero) */
 106         int     ri_fontscale;   /* fontheight * fontstride */
 107         int     ri_xscale;      /* fontwidth * pelbytes */
 108         int     ri_yscale;      /* fontheight * stride */
 109         u_char  *ri_origbits;   /* where screen bits actually start */
 110         int     ri_xorigin;     /* where ri_bits begins (x) */
 111         int     ri_yorigin;     /* where ri_bits begins (y) */
 112         int32_t ri_devcmap[16]; /* color -\*[Gt] framebuffer data */
 113
 114         /*
 115          * The emulops you need to use, and the screen caps for wscons
 116          */
 117         struct  wsdisplay_emulops ri_ops;
 118         int     ri_caps;
 119
 120         /*
 121          * Callbacks so we can share some code
 122          */
 123         void    (*ri_do_cursor)(struct rasops_info *);
 124 };
 125 .Ed
 126 .Pp
 127 Valid values for the
 128 .Em ri_flg
 129 member are:
 130 .Pp
 131 .Bl -tag -offset indent -width RI_CURSORCLIP -compact
 132 .It  RI_FULLCLEAR
 133 eraserows() hack to clear full screen
 134 .It  RI_FORCEMONO
 135 monochrome output even if we can do color
 136 .It  RI_BSWAP
 137 framebuffer endianness doesn't match CPU
 138 .It  RI_CURSOR
 139 cursor is switched on
 140 .It  RI_CLEAR
 141 clear display on startup
 142 .It  RI_CENTER
 143 center onscreen output
 144 .It  RI_CURSORCLIP
 145 cursor is currently clipped
 146 .It  RI_CFGDONE
 147 .Fn rasops_reconfig
 148 completed successfully
 149 .El
 150 .Sh FUNCTIONS
 151 .Bl -tag -width compact
 152 .It Fn rasops_init "ri" "wantrows" "wantcols"
 153 Initialise a
 154 .Em rasops_info
 155 descriptor.
 156 The arguments
 157 .Fa wantrows
 158 and
 159 .Fa wantcols
 160 are the number of rows and columns we'd like.
 161 In terms of optimization, fonts that are a multiple of 8 pixels wide
 162 work the best.
 163 .It Fn rasops_reconfig "ri" "wantrows" "wantcols"
 164 Reconfigure a
 165 .Em rasops_info
 166 descriptor because parameters have changed in some way.
 167 The arguments
 168 .Fa wantrows
 169 and
 170 .Fa wantcols
 171 are the number of rows and columns we'd like.
 172 If calling
 173 .Fn rasops_reconfig
 174 to change the font and ri_wsfcookie \*[Ge] 0, you must call
 175 .Fn wsfont_unlock
 176 on it, and reset it to -1 (or a new, valid cookie).
 177 .El
 178 .Sh CODE REFERENCES
 179 This section describes places within the
 180 .Nx
 181 source tree where actual code implementing or using the rasops
 182 subsystem can be found.
 183 All pathnames are relative to
 184 .Pa /usr/src .
 185 .Pp
 186 The rasops subsystem is implemented within the directory
 187 .Pa sys/dev/rasops .
 188 The
 189 .Nm
 190 module itself is implemented within the file
 191 .Pa sys/dev/rasops/rasops.c .
 192 .Sh SEE ALSO
 193 .Xr intro 9 ,
 194 .Xr wscons 9 ,
 195 .Xr wsdisplay 9 ,
 196 .Xr wsfont 9
 197 .Sh HISTORY
 198 The
 199 .Nm
 200 subsystem appeared in
 201 .Nx 1.5 .
 202 .Sh AUTHORS
 203 The
 204 .Nm
 205 subsystem was written by
 206 .An Andrew Doran
 207 .Aq ad@NetBSD.org .