1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3  * (C) Copyright 2017
4  * Mario Six,  Guntermann & Drunck GmbH, mario.six@gdsys.cc
5  */
6 
7 #ifndef _VIDEO_OSD_H_
8 #define _VIDEO_OSD_H_
9 
10 struct video_osd_info {
11 	/* The width of the OSD display in columns */
12 	uint width;
13 	/* The height of the OSD display in rows */
14 	uint height;
15 	/* The major version of the OSD device */
16 	uint major_version;
17 	/* The minor version of the OSD device */
18 	uint minor_version;
19 };
20 
21 /**
22  * struct video_osd_ops - driver operations for OSD uclass
23  *
24  * The OSD uclass implements support for text-oriented on-screen displays,
25  * which are taken to be devices that independently display a graphical
26  * text-based overlay over the video output of an associated display.
27  *
28  * The functions defined by the uclass support writing text to the display in
29  * either a generic form (by specifying a string, a driver-specific color value
30  * for the text, and screen coordinates in rows and columns) or a
31  * driver-specific form (by specifying "raw" driver-specific data to display at
32  * a given coordinate).
33  *
34  * Functions to read device information and set the size of the virtual OSD
35  * screen (in rows and columns) are also supported.
36  *
37  * Drivers should support these operations unless otherwise noted. These
38  * operations are intended to be used by uclass code, not directly from
39  * other code.
40  */
41 struct video_osd_ops {
42 	/**
43 	 * get_info() - Get information about a OSD instance
44 	 *
45 	 * A OSD instance may keep some internal data about itself. This
46 	 * function can be used to access this data.
47 	 *
48 	 * @dev:	OSD instance to query.
49 	 * @info:	Pointer to a structure that takes the information read
50 	 *		from the OSD instance.
51 	 * @return 0 if OK, -ve on error.
52 	 */
53 	int (*get_info)(struct udevice *dev, struct video_osd_info *info);
54 
55 	/**
56 	 * set_mem() - Write driver-specific text data to OSD screen
57 	 *
58 	 * The passed data are device-specific, and it's up to the driver how
59 	 * to interpret them. How the count parameter is interpreted is also
60 	 * driver-specific; most likely the given data will be written to the
61 	 * OSD count times back-to-back, which is e.g. convenient for filling
62 	 * areas of the OSD with a single character.
63 	 *
64 	 * For example a invocation of
65 	 *
66 	 * video_osd_set_mem(dev, 0, 0, "A", 1, 10);
67 	 *
68 	 * will write the device-specific text data "A" to the positions (0, 0)
69 	 * to (9, 0) on the OSD.
70 	 *
71 	 * Device-specific text data may, e.g. be a special encoding of glyphs
72 	 * to display and color values in binary format.
73 	 *
74 	 * @dev:	OSD instance to write to.
75 	 * @col:	Horizontal character coordinate to write to.
76 	 * @row		Vertical character coordinate to write to.
77 	 * @buf:	Array containing device-specific data to write to the
78 	 *		specified coordinate on the OSD screen.
79 	 * @buflen:	Length of the data in the passed buffer (in byte).
80 	 * @count:	Write count many repetitions of the given text data
81 	 * @return 0 if OK, -ve on error.
82 	 */
83 	int (*set_mem)(struct udevice *dev, uint col, uint row, u8 *buf,
84 		       size_t buflen, uint count);
85 
86 	/**
87 	 * set_size() - Set the position and dimension of the OSD's
88 	 *              writeable window
89 	 *
90 	 * @dev:	OSD instance to write to.
91 	 * @col		The number of characters in the window's columns
92 	 * @row		The number of characters in the window's rows
93 	 * @return 0 if OK, -ve on error.
94 	 */
95 	int (*set_size)(struct udevice *dev, uint col, uint row);
96 
97 	/**
98 	 * print() - Print a string in a given color to specified coordinates
99 	 *	     on the OSD
100 	 *
101 	 * @dev:	OSD instance to write to.
102 	 * @col		The x-coordinate of the position the string should be
103 	 *		written to
104 	 * @row		The y-coordinate of the position the string should be
105 	 *		written to
106 	 * @color:	The color in which the specified string should be
107 	 *		printed; the interpretation of the value is
108 	 *		driver-specific, and possible values should be defined
109 	 *		e.g. in a driver include file.
110 	 * @text:	The string data that should be printed on the OSD
111 	 * @return 0 if OK, -ve on error.
112 	 */
113 	int (*print)(struct udevice *dev, uint col, uint row, ulong color,
114 		     char *text);
115 };
116 
117 #define video_osd_get_ops(dev)	((struct video_osd_ops *)(dev)->driver->ops)
118 
119 /**
120  * video_osd_get_info() - Get information about a OSD instance
121  *
122  * A OSD instance may keep some internal data about itself. This function can
123  * be used to access this data.
124  *
125  * @dev:	OSD instance to query.
126  * @info:	Pointer to a structure that takes the information read from the
127  *		OSD instance.
128  * @return 0 if OK, -ve on error.
129  */
130 int video_osd_get_info(struct udevice *dev, struct video_osd_info *info);
131 
132 /**
133  * video_osd_set_mem() - Write text data to OSD memory
134  *
135  * The passed data are device-specific, and it's up to the driver how to
136  * interpret them. How the count parameter is interpreted is also
137  * driver-specific; most likely the given data will be written to the OSD count
138  * times back-to-back, which is e.g. convenient for filling areas of the OSD
139  * with a single character.
140  *
141  * For example a invocation of
142  *
143  * video_osd_set_mem(dev, 0, 0, "A", 1, 10);
144  *
145  * will write the device-specific text data "A" to the positions (0, 0) to (9,
146  * 0) on the OSD.
147  *
148  * Device-specific text data may, e.g. be a special encoding of glyphs to
149  * display and color values in binary format.
150  *
151  * @dev:	OSD instance to write to.
152  * @col:	Horizontal character coordinate to write to.
153  * @row		Vertical character coordinate to write to.
154  * @buf:	Array containing device-specific data to write to the specified
155  *		coordinate on the OSD screen.
156  * @buflen:	Length of the data in the passed buffer (in byte).
157  * @count:	Write count many repetitions of the given text data
158  * @return 0 if OK, -ve on error.
159  */
160 int video_osd_set_mem(struct udevice *dev, uint col, uint row, u8 *buf,
161 		      size_t buflen, uint count);
162 
163 /**
164  * video_osd_set_size() - Set the position and dimension of the OSD's
165  *              writeable window
166  *
167  * @dev:	OSD instance to write to.
168  * @col		The number of characters in the window's columns
169  * @row		The number of characters in the window's rows
170  * @return 0 if OK, -ve on error.
171  */
172 int video_osd_set_size(struct udevice *dev, uint col, uint row);
173 
174 /**
175  * video_osd_print() - Print a string in a given color to specified coordinates
176  *		       on the OSD
177  *
178  * @dev:	OSD instance to write to.
179  * @col		The x-coordinate of the position the string should be written
180  *		to
181  * @row		The y-coordinate of the position the string should be written
182  *		to
183  * @color:	The color in which the specified string should be printed; the
184  *		interpretation of the value is driver-specific, and possible
185  *		values should be defined e.g. in a driver include file.
186  * @text:	The string data that should be printed on the OSD
187  * @return 0 if OK, -ve on error.
188  */
189 int video_osd_print(struct udevice *dev, uint col, uint row, ulong color,
190 		    char *text);
191 
192 #endif /* !_VIDEO_OSD_H_ */
193