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
10struct 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 */
41struct 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 */
130int 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 */
160int 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 */
172int 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 */
189int video_osd_print(struct udevice *dev, uint col, uint row, ulong color,
190		    char *text);
191
192#endif /* !_VIDEO_OSD_H_ */
193