1/* SPDX-License-Identifier: GPL-2.0+ */ 2/* 3 * Copyright 2022 Google LLC 4 * Written by Simon Glass <sjg@chromium.org> 5 */ 6 7#ifndef __SCENE_H 8#define __SCENE_H 9 10#include <linux/list.h> 11 12struct udevice; 13 14/** 15 * enum expoact_type - types of actions reported by the expo 16 * 17 * @EXPOACT_NONE: no action 18 * @EXPOACT_POINT: menu item was highlighted (@id indicates which) 19 * @EXPOACT_SELECT: menu item was selected (@id indicates which) 20 * @EXPOACT_QUIT: request to exit the menu 21 */ 22enum expoact_type { 23 EXPOACT_NONE, 24 EXPOACT_POINT, 25 EXPOACT_SELECT, 26 EXPOACT_QUIT, 27}; 28 29/** 30 * struct expo_action - an action report by the expo 31 * 32 * @type: Action type (EXPOACT_NONE if there is no action) 33 * @select: Used for EXPOACT_POINT and EXPOACT_SELECT 34 * @id: ID number of the object affected. 35 */ 36struct expo_action { 37 enum expoact_type type; 38 union { 39 struct { 40 int id; 41 } select; 42 }; 43}; 44 45/** 46 * struct expo - information about an expo 47 * 48 * A group of scenes which can be presented to the user, typically to obtain 49 * input or to make a selection. 50 * 51 * @name: Name of the expo (allocated) 52 * @display: Display to use (`UCLASS_VIDEO`), or NULL to use text mode 53 * @scene_id: Current scene ID (0 if none) 54 * @next_id: Next ID number to use, for automatic allocation 55 * @action: Action selected by user. At present only one is supported, with the 56 * type set to EXPOACT_NONE if there is no action 57 * @text_mode: true to use text mode for the menu (no vidconsole) 58 * @priv: Private data for the controller 59 * @scene_head: List of scenes 60 * @str_head: list of strings 61 */ 62struct expo { 63 char *name; 64 struct udevice *display; 65 uint scene_id; 66 uint next_id; 67 struct expo_action action; 68 bool text_mode; 69 void *priv; 70 struct list_head scene_head; 71 struct list_head str_head; 72}; 73 74/** 75 * struct expo_string - a string that can be used in an expo 76 * 77 * @id: ID number of the string 78 * @str: String 79 * @sibling: Node to link this object to its siblings 80 */ 81struct expo_string { 82 uint id; 83 const char *str; 84 struct list_head sibling; 85}; 86 87/** 88 * struct scene - information about a scene in an expo 89 * 90 * A collection of text/image/menu items in an expo 91 * 92 * @expo: Expo this scene is part of 93 * @name: Name of the scene (allocated) 94 * @id: ID number of the scene 95 * @title: Title of the scene (allocated) 96 * @sibling: Node to link this scene to its siblings 97 * @obj_head: List of objects in the scene 98 */ 99struct scene { 100 struct expo *expo; 101 char *name; 102 uint id; 103 char *title; 104 struct list_head sibling; 105 struct list_head obj_head; 106}; 107 108/** 109 * enum scene_obj_t - type of a scene object 110 * 111 * @SCENEOBJT_NONE: Used to indicate that the type does not matter 112 * @SCENEOBJT_IMAGE: Image data to render 113 * @SCENEOBJT_TEXT: Text line to render 114 * @SCENEOBJT_MENU: Menu containing items the user can select 115 */ 116enum scene_obj_t { 117 SCENEOBJT_NONE = 0, 118 SCENEOBJT_IMAGE, 119 SCENEOBJT_TEXT, 120 SCENEOBJT_MENU, 121}; 122 123/** 124 * struct scene_obj - information about an object in a scene 125 * 126 * @scene: Scene that this object relates to 127 * @name: Name of the object (allocated) 128 * @id: ID number of the object 129 * @type: Type of this object 130 * @x: x position, in pixels from left side 131 * @y: y position, in pixels from top 132 * @hide: true if the object should be hidden 133 * @sibling: Node to link this object to its siblings 134 */ 135struct scene_obj { 136 struct scene *scene; 137 char *name; 138 uint id; 139 enum scene_obj_t type; 140 int x; 141 int y; 142 bool hide; 143 struct list_head sibling; 144}; 145 146/** 147 * struct scene_obj_img - information about an image object in a scene 148 * 149 * This is a rectangular image which is blitted onto the display 150 * 151 * @obj: Basic object information 152 * @data: Image data in BMP format 153 */ 154struct scene_obj_img { 155 struct scene_obj obj; 156 char *data; 157}; 158 159/** 160 * struct scene_obj_txt - information about a text object in a scene 161 * 162 * This is a single-line text object 163 * 164 * @obj: Basic object information 165 * @str_id: ID of the text string to display 166 * @font_name: Name of font (allocated by caller) 167 * @font_size: Nominal size of font in pixels 168 */ 169struct scene_obj_txt { 170 struct scene_obj obj; 171 uint str_id; 172 const char *font_name; 173 uint font_size; 174}; 175 176/** 177 * struct scene_obj_menu - information about a menu object in a scene 178 * 179 * A menu has a number of items which can be selected by the user 180 * 181 * It also has: 182 * 183 * - a text/image object (@pointer_id) which points to the current item 184 * (@cur_item_id) 185 * 186 * - a preview object which shows an image related to the current item 187 * 188 * @obj: Basic object information 189 * @title_id: ID of the title text, or 0 if none 190 * @cur_item_id: ID of the current menu item, or 0 if none 191 * @pointer_id: ID of the object pointing to the current selection 192 * @item_head: List of items in the menu 193 */ 194struct scene_obj_menu { 195 struct scene_obj obj; 196 uint title_id; 197 uint cur_item_id; 198 uint pointer_id; 199 struct list_head item_head; 200}; 201 202/** 203 * enum scene_menuitem_flags_t - flags for menu items 204 * 205 * @SCENEMIF_GAP_BEFORE: Add a gap before this item 206 */ 207enum scene_menuitem_flags_t { 208 SCENEMIF_GAP_BEFORE = 1 << 0, 209}; 210 211/** 212 * struct scene_menitem - a menu item in a menu 213 * 214 * A menu item has: 215 * 216 * - text object holding the name (short) and description (can be longer) 217 * - a text object holding the keypress 218 * 219 * @name: Name of the item (this is allocated by this call) 220 * @id: ID number of the object 221 * @key_id: ID of text object to use as the keypress to show 222 * @label_id: ID of text object to use as the label text 223 * @desc_id: ID of text object to use as the description text 224 * @preview_id: ID of the preview object, or 0 if none 225 * @flags: Flags for this item 226 * @sibling: Node to link this item to its siblings 227 */ 228struct scene_menitem { 229 char *name; 230 uint id; 231 uint key_id; 232 uint label_id; 233 uint desc_id; 234 uint preview_id; 235 uint flags; 236 struct list_head sibling; 237}; 238 239/** 240 * expo_new() - create a new expo 241 * 242 * Allocates a new expo 243 * 244 * @name: Name of expo (this is allocated by this call) 245 * @priv: Private data for the controller 246 * @expp: Returns a pointer to the new expo on success 247 * Returns: 0 if OK, -ENOMEM if out of memory 248 */ 249int expo_new(const char *name, void *priv, struct expo **expp); 250 251/** 252 * expo_destroy() - Destroy an expo and free all its memory 253 * 254 * @exp: Expo to destroy 255 */ 256void expo_destroy(struct expo *exp); 257 258/** 259 * expo_str() - add a new string to an expo 260 * 261 * @exp: Expo to update 262 * @name: Name to use (this is allocated by this call) 263 * @id: ID to use for the new object (0 to allocate one) 264 * @str: Pointer to text to display (allocated by caller) 265 * Returns: ID number for the object (typically @id), or -ve on error 266 */ 267int expo_str(struct expo *exp, const char *name, uint id, const char *str); 268 269/** 270 * expo_get_str() - Get a string by ID 271 * 272 * @exp: Expo to use 273 * @id: String ID to look up 274 * @returns string, or NULL if not found 275 */ 276const char *expo_get_str(struct expo *exp, uint id); 277 278/** 279 * expo_set_display() - set the display to use for a expo 280 * 281 * @exp: Expo to update 282 * @dev: Display to use (`UCLASS_VIDEO`), NULL to use text mode 283 * Returns: 0 (always) 284 */ 285int expo_set_display(struct expo *exp, struct udevice *dev); 286 287/** 288 * expo_set_scene_id() - Set the current scene ID 289 * 290 * @exp: Expo to update 291 * @scene_id: New scene ID to use (0 to select no scene) 292 * Returns: 0 if OK, -ENOENT if there is no scene with that ID 293 */ 294int expo_set_scene_id(struct expo *exp, uint scene_id); 295 296/** 297 * expo_render() - render the expo on the display / console 298 * 299 * @exp: Expo to render 300 * 301 * Returns: 0 if OK, -ECHILD if there is no current scene, -ENOENT if the 302 * current scene is not found, other error if something else goes wrong 303 */ 304int expo_render(struct expo *exp); 305 306/** 307 * exp_set_text_mode() - Controls whether the expo renders in text mode 308 * 309 * @exp: Expo to update 310 * @text_mode: true to use text mode, false to use the console 311 */ 312void exp_set_text_mode(struct expo *exp, bool text_mode); 313 314/** 315 * scene_new() - create a new scene in a expo 316 * 317 * The scene is given the ID @id which must be unique across all scenes, objects 318 * and items. The expo's @next_id is updated to at least @id + 1 319 * 320 * @exp: Expo to update 321 * @name: Name to use (this is allocated by this call) 322 * @id: ID to use for the new scene (0 to allocate one) 323 * @scnp: Returns a pointer to the new scene on success 324 * Returns: ID number for the scene (typically @id), or -ve on error 325 */ 326int scene_new(struct expo *exp, const char *name, uint id, struct scene **scnp); 327 328/** 329 * expo_lookup_scene_id() - Look up a scene by ID 330 * 331 * @exp: Expo to check 332 * @scene_id: Scene ID to look up 333 * @returns pointer to scene if found, else NULL 334 */ 335struct scene *expo_lookup_scene_id(struct expo *exp, uint scene_id); 336 337/** 338 * scene_title_set() - set the scene title 339 * 340 * @scn: Scene to update 341 * @title: Title to set, NULL if none (this is allocated by this call) 342 * Returns: 0 if OK, -ENOMEM if out of memory 343 */ 344int scene_title_set(struct scene *scn, const char *title); 345 346/** 347 * scene_obj_count() - Count the number of objects in a scene 348 * 349 * @scn: Scene to check 350 * Returns: number of objects in the scene, 0 if none 351 */ 352int scene_obj_count(struct scene *scn); 353 354/** 355 * scene_img() - add a new image to a scene 356 * 357 * @scn: Scene to update 358 * @name: Name to use (this is allocated by this call) 359 * @id: ID to use for the new object (0 to allocate one) 360 * @data: Pointer to image data 361 * @imgp: If non-NULL, returns the new object 362 * Returns: ID number for the object (typically @id), or -ve on error 363 */ 364int scene_img(struct scene *scn, const char *name, uint id, char *data, 365 struct scene_obj_img **imgp); 366 367/** 368 * scene_txt() - add a new text object to a scene 369 * 370 * @scn: Scene to update 371 * @name: Name to use (this is allocated by this call) 372 * @id: ID to use for the new object (0 to allocate one) 373 * @str_id: ID of the string to use 374 * @txtp: If non-NULL, returns the new object 375 * Returns: ID number for the object (typically @id), or -ve on error 376 */ 377int scene_txt(struct scene *scn, const char *name, uint id, uint str_id, 378 struct scene_obj_txt **txtp); 379 380/** 381 * scene_txt_str() - add a new string to expr and text object to a scene 382 * 383 * @scn: Scene to update 384 * @name: Name to use (this is allocated by this call) 385 * @id: ID to use for the new object (0 to allocate one) 386 * @str_id: ID of the string to use 387 * @str: Pointer to text to display (allocated by caller) 388 * @txtp: If non-NULL, returns the new object 389 * Returns: ID number for the object (typically @id), or -ve on error 390 */ 391int scene_txt_str(struct scene *scn, const char *name, uint id, uint str_id, 392 const char *str, struct scene_obj_txt **txtp); 393 394/** 395 * scene_menu() - create a menu 396 * 397 * @scn: Scene to update 398 * @name: Name to use (this is allocated by this call) 399 * @id: ID to use for the new object (0 to allocate one) 400 * @menup: If non-NULL, returns the new object 401 * Returns: ID number for the object (typically @id), or -ve on error 402 */ 403int scene_menu(struct scene *scn, const char *name, uint id, 404 struct scene_obj_menu **menup); 405 406/** 407 * scene_txt_set_font() - Set the font for an object 408 * 409 * @scn: Scene to update 410 * @id: ID of object to update 411 * @font_name: Font name to use (allocated by caller) 412 * @font_size: Font size to use (nominal height in pixels) 413 */ 414int scene_txt_set_font(struct scene *scn, uint id, const char *font_name, 415 uint font_size); 416 417/** 418 * scene_obj_set_pos() - Set the postion of an object 419 * 420 * @scn: Scene to update 421 * @id: ID of object to update 422 * @x: x position, in pixels from left side 423 * @y: y position, in pixels from top 424 * Returns: 0 if OK, -ENOENT if @id is invalid 425 */ 426int scene_obj_set_pos(struct scene *scn, uint id, int x, int y); 427 428/** 429 * scene_obj_set_hide() - Set whether an object is hidden 430 * 431 * The update happens when the expo is next rendered. 432 * 433 * @scn: Scene to update 434 * @id: ID of object to update 435 * @hide: true to hide the object, false to show it 436 * Returns: 0 if OK, -ENOENT if @id is invalid 437 */ 438int scene_obj_set_hide(struct scene *scn, uint id, bool hide); 439 440/** 441 * scene_menu_set_title() - Set the title of a menu 442 * 443 * @scn: Scene to update 444 * @id: ID of menu object to update 445 * @title_id: ID of text object to use as the title 446 * Returns: 0 if OK, -ENOENT if @id is invalid, -EINVAL if @title_id is invalid 447 */ 448int scene_menu_set_title(struct scene *scn, uint id, uint title_id); 449 450/** 451 * scene_menu_set_pointer() - Set the item pointer for a menu 452 * 453 * This is a visual indicator of the current item, typically a ">" character 454 * which sits next to the current item and moves when the user presses the 455 * up/down arrow keys 456 * 457 * @scn: Scene to update 458 * @id: ID of menu object to update 459 * @cur_item_id: ID of text or image object to use as a pointer to the current 460 * item 461 * Returns: 0 if OK, -ENOENT if @id is invalid, -EINVAL if @cur_item_id is invalid 462 */ 463int scene_menu_set_pointer(struct scene *scn, uint id, uint cur_item_id); 464 465/** 466 * scene_obj_get_hw() - Get width and height of an object in a scene 467 * 468 * @scn: Scene to check 469 * @id: ID of menu object to check 470 * @widthp: If non-NULL, returns width of object in pixels 471 * Returns: Height of object in pixels 472 */ 473int scene_obj_get_hw(struct scene *scn, uint id, int *widthp); 474 475/** 476 * scene_menuitem() - Add an item to a menu 477 * 478 * @scn: Scene to update 479 * @menu_id: ID of menu object to update 480 * @name: Name to use (this is allocated by this call) 481 * @id: ID to use for the new object (0 to allocate one) 482 * @key_id: ID of text object to use as the keypress to show 483 * @label_id: ID of text object to use as the label text 484 * @desc_id: ID of text object to use as the description text 485 * @preview_id: ID of object to use as the preview (text or image) 486 * @flags: Flags for this item (enum scene_menuitem_flags_t) 487 * @itemp: If non-NULL, returns the new object 488 * Returns: ID number for the item (typically @id), or -ve on error 489 */ 490int scene_menuitem(struct scene *scn, uint menu_id, const char *name, uint id, 491 uint key_id, uint label_id, uint desc_id, uint preview_id, 492 uint flags, struct scene_menitem **itemp); 493 494/** 495 * scene_arrange() - Arrange the scene to deal with object sizes 496 * 497 * Updates any menus in the scene so that their objects are in the right place. 498 * 499 * @scn: Scene to arrange 500 * Returns: 0 if OK, -ve on error 501 */ 502int scene_arrange(struct scene *scn); 503 504/** 505 * expo_send_key() - set a keypress to the expo 506 * 507 * @exp: Expo to receive the key 508 * @key: Key to send (ASCII or enum bootmenu_key) 509 * Returns: 0 if OK, -ECHILD if there is no current scene 510 */ 511int expo_send_key(struct expo *exp, int key); 512 513/** 514 * expo_action_get() - read user input from the expo 515 * 516 * @exp: Expo to check 517 * @act: Returns action 518 * Returns: 0 if OK, -EAGAIN if there was no action to return 519 */ 520int expo_action_get(struct expo *exp, struct expo_action *act); 521 522#endif /*__SCENE_H */ 523