include/video_osd.h

   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_ */