summaryrefslogtreecommitdiff
path: root/include/video_osd.h
blob: dc60bafa8a6ec3d21cf7701ead0148defa891649 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
/* SPDX-License-Identifier: GPL-2.0+ */
/*
 * (C) Copyright 2017
 * Mario Six,  Guntermann & Drunck GmbH, mario.six@gdsys.cc
 */

#ifndef _VIDEO_OSD_H_
#define _VIDEO_OSD_H_

struct video_osd_info {
	/* The width of the OSD display in columns */
	uint width;
	/* The height of the OSD display in rows */
	uint height;
	/* The major version of the OSD device */
	uint major_version;
	/* The minor version of the OSD device */
	uint minor_version;
};

/**
 * struct video_osd_ops - driver operations for OSD uclass
 *
 * The OSD uclass implements support for text-oriented on-screen displays,
 * which are taken to be devices that independently display a graphical
 * text-based overlay over the video output of an associated display.
 *
 * The functions defined by the uclass support writing text to the display in
 * either a generic form (by specifying a string, a driver-specific color value
 * for the text, and screen coordinates in rows and columns) or a
 * driver-specific form (by specifying "raw" driver-specific data to display at
 * a given coordinate).
 *
 * Functions to read device information and set the size of the virtual OSD
 * screen (in rows and columns) are also supported.
 *
 * Drivers should support these operations unless otherwise noted. These
 * operations are intended to be used by uclass code, not directly from
 * other code.
 */
struct video_osd_ops {
	/**
	 * get_info() - Get information about a OSD instance
	 *
	 * A OSD instance may keep some internal data about itself. This
	 * function can be used to access this data.
	 *
	 * @dev:	OSD instance to query.
	 * @info:	Pointer to a structure that takes the information read
	 *		from the OSD instance.
	 * @return 0 if OK, -ve on error.
	 */
	int (*get_info)(struct udevice *dev, struct video_osd_info *info);

	/**
	 * set_mem() - Write driver-specific text data to OSD screen
	 *
	 * The passed data are device-specific, and it's up to the driver how
	 * to interpret them. How the count parameter is interpreted is also
	 * driver-specific; most likely the given data will be written to the
	 * OSD count times back-to-back, which is e.g. convenient for filling
	 * areas of the OSD with a single character.
	 *
	 * For example a invocation of
	 *
	 * video_osd_set_mem(dev, 0, 0, "A", 1, 10);
	 *
	 * will write the device-specific text data "A" to the positions (0, 0)
	 * to (9, 0) on the OSD.
	 *
	 * Device-specific text data may, e.g. be a special encoding of glyphs
	 * to display and color values in binary format.
	 *
	 * @dev:	OSD instance to write to.
	 * @col:	Horizontal character coordinate to write to.
	 * @row		Vertical character coordinate to write to.
	 * @buf:	Array containing device-specific data to write to the
	 *		specified coordinate on the OSD screen.
	 * @buflen:	Length of the data in the passed buffer (in byte).
	 * @count:	Write count many repetitions of the given text data
	 * @return 0 if OK, -ve on error.
	 */
	int (*set_mem)(struct udevice *dev, uint col, uint row, u8 *buf,
		       size_t buflen, uint count);

	/**
	 * set_size() - Set the position and dimension of the OSD's
	 *              writeable window
	 *
	 * @dev:	OSD instance to write to.
	 * @col		The number of characters in the window's columns
	 * @row		The number of characters in the window's rows
	 * @return 0 if OK, -ve on error.
	 */
	int (*set_size)(struct udevice *dev, uint col, uint row);

	/**
	 * print() - Print a string in a given color to specified coordinates
	 *	     on the OSD
	 *
	 * @dev:	OSD instance to write to.
	 * @col		The x-coordinate of the position the string should be
	 *		written to
	 * @row		The y-coordinate of the position the string should be
	 *		written to
	 * @color:	The color in which the specified string should be
	 *		printed; the interpretation of the value is
	 *		driver-specific, and possible values should be defined
	 *		e.g. in a driver include file.
	 * @text:	The string data that should be printed on the OSD
	 * @return 0 if OK, -ve on error.
	 */
	int (*print)(struct udevice *dev, uint col, uint row, ulong color,
		     char *text);
};

#define video_osd_get_ops(dev)	((struct video_osd_ops *)(dev)->driver->ops)

/**
 * video_osd_get_info() - Get information about a OSD instance
 *
 * A OSD instance may keep some internal data about itself. This function can
 * be used to access this data.
 *
 * @dev:	OSD instance to query.
 * @info:	Pointer to a structure that takes the information read from the
 *		OSD instance.
 * Return: 0 if OK, -ve on error.
 */
int video_osd_get_info(struct udevice *dev, struct video_osd_info *info);

/**
 * video_osd_set_mem() - Write text data to OSD memory
 *
 * The passed data are device-specific, and it's up to the driver how to
 * interpret them. How the count parameter is interpreted is also
 * driver-specific; most likely the given data will be written to the OSD count
 * times back-to-back, which is e.g. convenient for filling areas of the OSD
 * with a single character.
 *
 * For example a invocation of
 *
 * video_osd_set_mem(dev, 0, 0, "A", 1, 10);
 *
 * will write the device-specific text data "A" to the positions (0, 0) to (9,
 * 0) on the OSD.
 *
 * Device-specific text data may, e.g. be a special encoding of glyphs to
 * display and color values in binary format.
 *
 * @dev:	OSD instance to write to.
 * @col:	Horizontal character coordinate to write to.
 * @row		Vertical character coordinate to write to.
 * @buf:	Array containing device-specific data to write to the specified
 *		coordinate on the OSD screen.
 * @buflen:	Length of the data in the passed buffer (in byte).
 * @count:	Write count many repetitions of the given text data
 * Return: 0 if OK, -ve on error.
 */
int video_osd_set_mem(struct udevice *dev, uint col, uint row, u8 *buf,
		      size_t buflen, uint count);

/**
 * video_osd_set_size() - Set the position and dimension of the OSD's
 *              writeable window
 *
 * @dev:	OSD instance to write to.
 * @col		The number of characters in the window's columns
 * @row		The number of characters in the window's rows
 * Return: 0 if OK, -ve on error.
 */
int video_osd_set_size(struct udevice *dev, uint col, uint row);

/**
 * video_osd_print() - Print a string in a given color to specified coordinates
 *		       on the OSD
 *
 * @dev:	OSD instance to write to.
 * @col		The x-coordinate of the position the string should be written
 *		to
 * @row		The y-coordinate of the position the string should be written
 *		to
 * @color:	The color in which the specified string should be printed; the
 *		interpretation of the value is driver-specific, and possible
 *		values should be defined e.g. in a driver include file.
 * @text:	The string data that should be printed on the OSD
 * Return: 0 if OK, -ve on error.
 */
int video_osd_print(struct udevice *dev, uint col, uint row, ulong color,
		    char *text);

#endif /* !_VIDEO_OSD_H_ */