[J-u-boot.git] / include / video_osd.h

/* SPDX-License-Identifier: GPL-2.0+ */
/*
 * (C) Copyright 2017
 * Mario Six,  Guntermann & Drunck GmbH, [email protected]
 */

#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_ */
Commit	Line	Data
39a336f1 MS	1	/* SPDX-License-Identifier: GPL-2.0+ */
	2	/*
	3	* (C) Copyright 2017
	4	* Mario Six, Guntermann & Drunck GmbH, [email protected]
	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_ */