xref: /openbsd-src/share/man/man9/rasops.9 (revision d745b72e7eff8f1f6315e83c6a81b658fc7e73ca)
1*d745b72eSfcambus.\"	$OpenBSD: rasops.9,v 1.18 2017/08/21 11:49:50 fcambus Exp $
2dc0ae18eSjason.\"     $NetBSD: rasops.9,v 1.4 2002/02/13 08:18:50 ross Exp $
3dc0ae18eSjason.\"
4dc0ae18eSjason.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
5dc0ae18eSjason.\" All rights reserved.
6dc0ae18eSjason.\"
7dc0ae18eSjason.\" This code is derived from software contributed to The NetBSD Foundation
8dc0ae18eSjason.\" by Gregory McGarry.
9dc0ae18eSjason.\"
10dc0ae18eSjason.\" Redistribution and use in source and binary forms, with or without
11dc0ae18eSjason.\" modification, are permitted provided that the following conditions
12dc0ae18eSjason.\" are met:
13dc0ae18eSjason.\" 1. Redistributions of source code must retain the above copyright
14dc0ae18eSjason.\"    notice, this list of conditions and the following disclaimer.
15dc0ae18eSjason.\" 2. Redistributions in binary form must reproduce the above copyright
16dc0ae18eSjason.\"    notice, this list of conditions and the following disclaimer in the
17dc0ae18eSjason.\"    documentation and/or other materials provided with the distribution.
18dc0ae18eSjason.\"
19dc0ae18eSjason.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
20dc0ae18eSjason.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21dc0ae18eSjason.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22dc0ae18eSjason.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
23dc0ae18eSjason.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24dc0ae18eSjason.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25dc0ae18eSjason.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26dc0ae18eSjason.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27dc0ae18eSjason.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28dc0ae18eSjason.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29dc0ae18eSjason.\" POSSIBILITY OF SUCH DAMAGE.
30dc0ae18eSjason.\"
31*d745b72eSfcambus.Dd $Mdocdate: August 21 2017 $
32dc0ae18eSjason.Dt RASOPS 9
33dc0ae18eSjason.Os
34dc0ae18eSjason.Sh NAME
35dc0ae18eSjason.Nm rasops ,
36dc0ae18eSjason.Nm rasops_init ,
37dc0ae18eSjason.Nm rasops_reconfig
38dc0ae18eSjason.Nd raster display operations
39dc0ae18eSjason.Sh SYNOPSIS
40dddd2645Sschwarze.In dev/wscons/wsdisplayvar.h
41dddd2645Sschwarze.In dev/rasops/rasops.h
42dc0ae18eSjason.Ft int
43dc0ae18eSjason.Fn rasops_init "struct rasops_info *ri" "int wantrows" "int wantcols"
44dc0ae18eSjason.Ft int
45dc0ae18eSjason.Fn rasops_reconfig "struct rasops_info *ri" "int wantrows" "int wantcols"
46dc0ae18eSjason.Sh DESCRIPTION
47dc0ae18eSjasonThe
48dc0ae18eSjason.Nm
49dc0ae18eSjasonsubsystem is a set of raster operations for
50cb4b231eSschwarze.Xr wscons 4 .
51dc0ae18eSjason.Pp
52dc0ae18eSjasonThe primary data type for using the raster operations is the
53dc0ae18eSjason.Em rasops_info
54dc0ae18eSjasonstructure in
55dc0ae18eSjason.Pa dev/rasops/rasops.h :
56dc0ae18eSjason.Bd -literal
57dc0ae18eSjasonstruct rasops_info {
58dc0ae18eSjason
59dc0ae18eSjason	/*
60dc0ae18eSjason	 * These must be filled in by the caller
61dc0ae18eSjason	 */
62dc0ae18eSjason	int	ri_depth;	/* depth in bits */
63dc0ae18eSjason	u_char	*ri_bits;	/* ptr to bits */
64dc0ae18eSjason	int	ri_width;	/* width (pels) */
65dc0ae18eSjason	int	ri_height;	/* height (pels) */
66dc0ae18eSjason	int	ri_stride;	/* stride in bytes */
67dc0ae18eSjason
68dc0ae18eSjason	/*
69dc0ae18eSjason	 * These can optionally be left zeroed out. If you fill ri_font,
70dc0ae18eSjason	 * but aren't using wsfont, set ri_wsfcookie to -1.
71dc0ae18eSjason	 */
72dc0ae18eSjason	struct	wsdisplay_font *ri_font;
73dc0ae18eSjason	int	ri_wsfcookie;	/* wsfont cookie */
74dc0ae18eSjason	void	*ri_hw;		/* driver private data */
7555fee4a5Skettenis	struct wsdisplay_charcell *ri_bs; /* character backing store */
76dc0ae18eSjason	int	ri_crow;	/* cursor row */
77dc0ae18eSjason	int	ri_ccol;	/* cursor column */
78dc0ae18eSjason	int	ri_flg;		/* various operational flags */
79dc0ae18eSjason
80dc0ae18eSjason	/*
81dc0ae18eSjason	 * These are optional and will default if zero. Meaningless
82dc0ae18eSjason	 * on depths other than 15, 16, 24 and 32 bits per pel. On
83dc0ae18eSjason	 * 24 bit displays, ri_{r,g,b}num must be 8.
84dc0ae18eSjason	 */
85dc0ae18eSjason	u_char	ri_rnum;	/* number of bits for red */
86dc0ae18eSjason	u_char	ri_gnum;	/* number of bits for green */
87dc0ae18eSjason	u_char	ri_bnum;	/* number of bits for blue */
88dc0ae18eSjason	u_char	ri_rpos;	/* which bit red starts at */
89dc0ae18eSjason	u_char	ri_gpos;	/* which bit green starts at */
90dc0ae18eSjason	u_char	ri_bpos;	/* which bit blue starts at */
91dc0ae18eSjason
92dc0ae18eSjason	/*
93dc0ae18eSjason	 * These are filled in by rasops_init()
94dc0ae18eSjason	 */
95dc0ae18eSjason	int	ri_emuwidth;	/* width we actually care about */
96dc0ae18eSjason	int	ri_emuheight;	/* height we actually care about */
97dc0ae18eSjason	int	ri_emustride;	/* bytes per row we actually care about */
98dc0ae18eSjason	int	ri_rows;	/* number of rows (characters) */
99dc0ae18eSjason	int	ri_cols;	/* number of columns (characters) */
100dc0ae18eSjason	int	ri_delta;	/* row delta in bytes */
101dc0ae18eSjason	int	ri_pelbytes;	/* bytes per pel (may be zero) */
102dc0ae18eSjason	int	ri_fontscale;	/* fontheight * fontstride */
103dc0ae18eSjason	int	ri_xscale;	/* fontwidth * pelbytes */
104dc0ae18eSjason	int	ri_yscale;	/* fontheight * stride */
105dc0ae18eSjason	u_char  *ri_origbits;	/* where screen bits actually start */
106dc0ae18eSjason	int	ri_xorigin;	/* where ri_bits begins (x) */
107dc0ae18eSjason	int	ri_yorigin;	/* where ri_bits begins (y) */
108dc0ae18eSjason	int32_t	ri_devcmap[16]; /* color -\*[Gt] framebuffer data */
109dc0ae18eSjason
110dc0ae18eSjason	/*
111dc0ae18eSjason	 * The emulops you need to use, and the screen caps for wscons
112dc0ae18eSjason	 */
113dc0ae18eSjason	struct	wsdisplay_emulops ri_ops;
114dc0ae18eSjason	int	ri_caps;
115dc0ae18eSjason
116dc0ae18eSjason	/*
117dc0ae18eSjason	 * Callbacks so we can share some code
118dc0ae18eSjason	 */
119dc0ae18eSjason	void	(*ri_do_cursor)(struct rasops_info *);
120dc0ae18eSjason	void	(*ri_updatecursor)(struct rasops_info *);
121a2c60493Smiod
122a2c60493Smiod#if NRASOPS_ROTATION > 0
123a2c60493Smiod	/* Used to intercept putchar to permit display rotation */
124a2c60493Smiod	struct	wsdisplay_emulops ri_real_ops;
125a2c60493Smiod#endif
126dc0ae18eSjason};
127dc0ae18eSjason.Ed
128dc0ae18eSjason.Pp
129a2c60493SmiodThe value of the
130dc0ae18eSjason.Em ri_flg
13128c2aadcSjmcmember is formed by OR'ing the following values:
132dc0ae18eSjason.Pp
133c27a5a61Sfcambus.Bl -tag -offset indent -width RI_CLEARMARGINS -compact
134dc0ae18eSjason.It RI_FULLCLEAR
135a2c60493SmiodForce eraserows() to clear the whole screen instead of only text lines,
13628c2aadcSjmcwhen invoked with an
137a2c60493Smiod.Em nrows
13828c2aadcSjmcparameter equal to the number of text lines.
139dc0ae18eSjason.It RI_FORCEMONO
140a2c60493SmiodDo not output coloured text, even if the display supports it.
141dc0ae18eSjason.It RI_BSWAP
142a2c60493SmiodSpecifies that the frame buffer endianness is different from the CPU's.
143dc0ae18eSjason.It RI_CURSOR
144a2c60493SmiodSet when the text cursor is enabled.
145dc0ae18eSjason.It RI_CLEAR
146a2c60493SmiodClear the display upon initialization.
147c27a5a61Sfcambus.It RI_CLEARMARGINS
148c27a5a61SfcambusClear display margins upon initialization.
149dc0ae18eSjason.It RI_CENTER
150a2c60493SmiodCenter the text area.
151a2c60493Smiod.\" Only honoured if option RASOPS_CLIPPING which we don't use.
152a2c60493Smiod.\" .It RI_CURSORCLIP
153a2c60493Smiod.\" Cursor is currently clipped
154a2c60493Smiod.It RI_ROTATE_CW
155a2c60493SmiodRotate the text display quarter clockwise.
156*d745b72eSfcambus.It RI_ROTATE_CCW
157*d745b72eSfcambusRotate the text display quarter counter-clockwise.
158dc0ae18eSjason.It RI_CFGDONE
159dc0ae18eSjason.Fn rasops_reconfig
160dc0ae18eSjasoncompleted successfully
16198517f2cSkettenis.It RI_VCONS
16298517f2cSkettenisSupport the use of multiple screens.
1632d72074fSmpi.It RI_WRONLY
1642d72074fSmpiDo not read back pixels from the frame buffer memory when performing
1652d72074fSmpiscreen-to-screen copy operations.
1662d72074fSmpiThis flag is ignored unless
1672d72074fSmpi.Dv RI_VCONS
16855fee4a5Skettenisis set or the
16955fee4a5Skettenis.Em ri_bs
17055fee4a5Skettenismember is set.
171dc0ae18eSjason.El
172dc0ae18eSjason.Sh FUNCTIONS
173dc0ae18eSjason.Bl -tag -width compact
174dc0ae18eSjason.It Fn rasops_init "ri" "wantrows" "wantcols"
175dc0ae18eSjasonInitialise a
176dc0ae18eSjason.Em rasops_info
177530175d9Sderaadtdescriptor.
178954ddbd6SmpechThe arguments
179dc0ae18eSjason.Fa wantrows
180dc0ae18eSjasonand
181dc0ae18eSjason.Fa wantcols
182954ddbd6Smpechare the number of rows and columns we'd like.
183954ddbd6SmpechIn terms of
184dc0ae18eSjasonoptimization, fonts that are a multiple of 8 pixels wide work the
185dc0ae18eSjasonbest.
186dc0ae18eSjason.It Fn rasops_reconfig "ri" "wantrows" "wantcols"
187dc0ae18eSjasonReconfigure a
188dc0ae18eSjason.Em rasops_info
189954ddbd6Smpechdescriptor because parameters have changed in some way.
190954ddbd6SmpechThe arguments
191dc0ae18eSjason.Fa wantrows
192dc0ae18eSjasonand
193dc0ae18eSjason.Fa wantcols
194954ddbd6Smpechare the number of rows and columns we'd like.
195954ddbd6SmpechIf calling
196dc0ae18eSjason.Fn rasops_reconfig
197dc0ae18eSjasonto change the font and ri_wsfcookie \*[Ge] 0, you must call
198dc0ae18eSjason.Fn wsfont_unlock
199dc0ae18eSjasonon it, and reset it to -1 (or a new, valid cookie).
200dc0ae18eSjason.El
201dc0ae18eSjason.Sh CODE REFERENCES
202dc0ae18eSjasonThis section describes places within the
203dc0ae18eSjason.Ox
204dc0ae18eSjasonsource tree where actual code implementing or utilising the rasops
205954ddbd6Smpechsubsystem can be found.
206954ddbd6SmpechAll pathnames are relative to
207dc0ae18eSjason.Pa /usr/src .
208dc0ae18eSjason.Pp
209dc0ae18eSjasonThe rasops subsystem is implemented within the directory
210dc0ae18eSjason.Pa sys/dev/rasops .
211dc0ae18eSjasonThe
212dc0ae18eSjason.Nm
213ed24e521Sjmcmodule itself is implemented within the file
214dc0ae18eSjason.Pa sys/dev/rasops/rasops.c .
215dc0ae18eSjason.Sh SEE ALSO
216dc0ae18eSjason.Xr intro 9
217dc0ae18eSjason.\" XXX These don't exist yet
218dc0ae18eSjason.\" .Xr wscons 9 ,
219dc0ae18eSjason.\" .Xr wsdisplay 9 ,
220dc0ae18eSjason.\" .Xr wsfont 9
221dc0ae18eSjason.Sh HISTORY
222dc0ae18eSjasonThe
223dc0ae18eSjason.Nm
224dc0ae18eSjasonsubsystem appeared in
225dc0ae18eSjason.Nx 1.5
226dc0ae18eSjasonand
227dc0ae18eSjason.Ox
228dc0ae18eSjasonfirst support appeared in
229dc0ae18eSjason.Ox 2.9 .
230dc0ae18eSjason.Sh AUTHORS
231d281945cSjaredy.An -nosplit
232dc0ae18eSjasonThe
233dc0ae18eSjason.Nm
234dc0ae18eSjasonsubsystem was written by
235f0641c22Sschwarze.An Andrew Doran Aq Mt ad@NetBSD.org .
236a2c60493SmiodDisplay rotation was written by
237f0641c22Sschwarze.An Christopher Pascoe Aq Mt pascoe@openbsd.org .
238a2c60493Smiod.Sh CAVEATS
239a2c60493SmiodDisplay rotation only works for 16bpp displays.
240