boot/scene_internal.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Internal header file for scenes
   4  *
   5  * Copyright 2022 Google LLC
   6  * Written by Simon Glass <sjg@chromium.org>
   7  */
   8
   9 #ifndef __SCENE_INTERNAL_H
  10 #define __SCENE_INTERNAL_H
  11
  12 struct vidconsole_bbox;
  13
  14 typedef int (*expo_scene_obj_iterator)(struct scene_obj *obj, void *priv);
  15
  16 /**
  17  * expo_lookup_scene_id() - Look up a scene ID
  18  *
  19  * @exp: Expo to use
  20  * @id: scene ID to look up
  21  * Returns: Scene for that ID, or NULL if none
  22  */
  23 struct scene *expo_lookup_scene_id(struct expo *exp, uint scene_id);
  24
  25 /**
  26  * resolve_id() - Automatically allocate an ID if needed
  27  *
  28  * @exp: Expo to use
  29  * @id: ID to use, or 0 to auto-allocate one
  30  * Returns: Either @id, or the auto-allocated ID
  31  */
  32 uint resolve_id(struct expo *exp, uint id);
  33
  34 /**
  35  * scene_obj_find() - Find an object in a scene
  36  *
  37  * Note that @type is used to restrict the search when the object type is known.
  38  * If any type is acceptable, set @type to SCENEOBJT_NONE
  39  *
  40  * @scn: Scene to search
  41  * @id: ID of object to find
  42  * @type: Type of the object, or SCENEOBJT_NONE to match any type
  43  * Returns: Object found, or NULL if not found
  44  */
  45 void *scene_obj_find(const struct scene *scn, uint id, enum scene_obj_t type);
  46
  47 /**
  48  * scene_obj_find_by_name() - Find an object in a scene by name
  49  *
  50  * @scn: Scene to search
  51  * @name: Name to search for
  52  */
  53 void *scene_obj_find_by_name(struct scene *scn, const char *name);
  54
  55 /**
  56  * scene_obj_add() - Add a new object to a scene
  57  *
  58  * @scn: Scene to update
  59  * @name: Name to use (this is allocated by this call)
  60  * @id: ID to use for the new object (0 to allocate one)
  61  * @type: Type of object to add
  62  * @size: Size to allocate for the object, in bytes
  63  * @objp: Returns a pointer to the new object (must not be NULL)
  64  * Returns: ID number for the object (generally @id), or -ve on error
  65  */
  66 int scene_obj_add(struct scene *scn, const char *name, uint id,
  67                   enum scene_obj_t type, uint size, struct scene_obj **objp);
  68
  69 /**
  70  * scene_obj_flag_clrset() - Adjust object flags
  71  *
  72  * @scn: Scene to update
  73  * @id: ID of object to update
  74  * @clr: Bits to clear in the object's flags
  75  * @set: Bits to set in the object's flags
  76  * Returns 0 if OK, -ENOENT if the object was not found
  77  */
  78 int scene_obj_flag_clrset(struct scene *scn, uint id, uint clr, uint set);
  79
  80 /**
  81  * scene_calc_dims() - Calculate the dimensions of the scene objects
  82  *
  83  * Updates the width and height of all objects based on their contents
  84  *
  85  * @scn: Scene to update
  86  * @do_menus: true to calculate only menus, false to calculate everything else
  87  * Returns 0 if OK, -ENOTSUPP if there is no graphical console
  88  */
  89 int scene_calc_dims(struct scene *scn, bool do_menus);
  90
  91 /**
  92  * scene_menu_arrange() - Set the position of things in the menu
  93  *
  94  * This updates any items associated with a menu to make sure they are
  95  * positioned correctly relative to the menu. It also selects the first item
  96  * if not already done
  97  *
  98  * @scn: Scene to update
  99  * @menu: Menu to process
 100  * Returns: 0 if OK, -ve on error
 101  */
 102 int scene_menu_arrange(struct scene *scn, struct scene_obj_menu *menu);
 103
 104 /**
 105  * scene_textline_arrange() - Set the position of things in a textline
 106  *
 107  * This updates any items associated with a textline to make sure they are
 108  * positioned correctly relative to the textline.
 109  *
 110  * @scn: Scene to update
 111  * @tline: textline to process
 112  * Returns: 0 if OK, -ve on error
 113  */
 114 int scene_textline_arrange(struct scene *scn, struct scene_obj_textline *tline);
 115
 116 /**
 117  * scene_apply_theme() - Apply a theme to a scene
 118  *
 119  * @scn: Scene to update
 120  * @theme: Theme to apply
 121  * Returns: 0 if OK, -ve on error
 122  */
 123 int scene_apply_theme(struct scene *scn, struct expo_theme *theme);
 124
 125 /**
 126  * scene_menu_send_key() - Send a key to a menu for processing
 127  *
 128  * @scn: Scene to use
 129  * @menu: Menu to use
 130  * @key: Key code to send (KEY_...)
 131  * @event: Place to put any event which is generated by the key
 132  * Returns: 0 if OK, -ENOTTY if there is no current menu item, other -ve on other
 133  *      error
 134  */
 135 int scene_menu_send_key(struct scene *scn, struct scene_obj_menu *menu, int key,
 136                         struct expo_action *event);
 137
 138 /**
 139  * scene_textline_send_key() - Send a key to a textline for processing
 140  *
 141  * @scn: Scene to use
 142  * @tline: textline to use
 143  * @key: Key code to send (KEY_...)
 144  * @event: Place to put any event which is generated by the key
 145  * Returns: 0 if OK (always)
 146  */
 147 int scene_textline_send_key(struct scene *scn, struct scene_obj_textline *tline,
 148                             int key, struct expo_action *event);
 149
 150 /**
 151  * scene_menu_destroy() - Destroy a menu in a scene
 152  *
 153  * @scn: Scene to destroy
 154  */
 155 void scene_menu_destroy(struct scene_obj_menu *menu);
 156
 157 /**
 158  * scene_menu_display() - Display a menu as text
 159  *
 160  * @menu: Menu to display
 161  * Returns: 0 if OK, -ENOENT if @id is invalid
 162  */
 163 int scene_menu_display(struct scene_obj_menu *menu);
 164
 165 /**
 166  * scene_destroy() - Destroy a scene and all its memory
 167  *
 168  * @scn: Scene to destroy
 169  */
 170 void scene_destroy(struct scene *scn);
 171
 172 /**
 173  * scene_render() - Render a scene
 174  *
 175  * This is called from expo_render()
 176  *
 177  * @scn: Scene to render
 178  * Returns: 0 if OK, -ve on error
 179  */
 180 int scene_render(struct scene *scn);
 181
 182 /**
 183  * scene_send_key() - set a keypress to a scene
 184  *
 185  * @scn: Scene to receive the key
 186  * @key: Key to send (KEYCODE_UP)
 187  * @event: Returns resulting event from this keypress
 188  * Returns: 0 if OK, -ve on error
 189  */
 190 int scene_send_key(struct scene *scn, int key, struct expo_action *event);
 191
 192 /**
 193  * scene_render_deps() - Render an object and its dependencies
 194  *
 195  * @scn: Scene to render
 196  * @id: Object ID to render (or 0 for none)
 197  * Returns: 0 if OK, -ve on error
 198  */
 199 int scene_render_deps(struct scene *scn, uint id);
 200
 201 /**
 202  * scene_menu_render_deps() - Render a menu and its dependencies
 203  *
 204  * Renders the menu and all of its attached objects
 205  *
 206  * @scn: Scene to render
 207  * @menu: Menu to render
 208  * Returns: 0 if OK, -ve on error
 209  */
 210 int scene_menu_render_deps(struct scene *scn, struct scene_obj_menu *menu);
 211
 212 /**
 213  * scene_textline_render_deps() - Render a textline and its dependencies
 214  *
 215  * Renders the textline and all of its attached objects
 216  *
 217  * @scn: Scene to render
 218  * @tline: textline to render
 219  * Returns: 0 if OK, -ve on error
 220  */
 221 int scene_textline_render_deps(struct scene *scn,
 222                                struct scene_obj_textline *tline);
 223
 224 /**
 225  * scene_menu_calc_dims() - Calculate the dimensions of a menu
 226  *
 227  * Updates the width and height of the menu based on its contents
 228  *
 229  * @menu: Menu to update
 230  * Returns 0 if OK, -ENOTSUPP if there is no graphical console
 231  */
 232 int scene_menu_calc_dims(struct scene_obj_menu *menu);
 233
 234 /**
 235  * scene_iter_objs() - Iterate through all scene objects
 236  *
 237  * @scn: Scene to process
 238  * @iter: Iterator to call on each object
 239  * @priv: Private data to pass to the iterator, in addition to the object
 240  * Return: 0 if OK, -ve on error
 241  */
 242 int scene_iter_objs(struct scene *scn, expo_scene_obj_iterator iter,
 243                     void *priv);
 244
 245 /**
 246  * expo_iter_scene_objects() - Iterate through all scene objects
 247  *
 248  * @exp: Expo to process
 249  * @iter: Iterator to call on each object
 250  * @priv: Private data to pass to the iterator, in addition to the object
 251  * Return: 0 if OK, -ve on error
 252  */
 253 int expo_iter_scene_objs(struct expo *exp, expo_scene_obj_iterator iter,
 254                          void *priv);
 255
 256 /**
 257  * scene_menuitem_find() - Find the menu item for an ID
 258  *
 259  * Looks up the menu to find the item with the given ID
 260  *
 261  * @menu: Menu to check
 262  * @id: ID to look for
 263  * Return: Menu item, or NULL if not found
 264  */
 265 struct scene_menitem *scene_menuitem_find(const struct scene_obj_menu *menu,
 266                                           int id);
 267
 268 /**
 269  * scene_menuitem_find_seq() - Find the menu item at a sequential position
 270  *
 271  * This numbers the items from 0 and returns the seq'th one
 272  *
 273  * @menu: Menu to check
 274  * @seq: Sequence number to look for
 275  * Return: menu item if found, else NULL
 276  */
 277 struct scene_menitem *scene_menuitem_find_seq(const struct scene_obj_menu *menu,
 278                                               uint seq);
 279
 280 /**
 281  * scene_bbox_union() - update bouding box with the demensions of an object
 282  *
 283  * Updates @bbox so that it encompasses the bounding box of object @id
 284  *
 285  * @snd: Scene containing object
 286  * @id: Object id
 287  * @inset: Amount of inset to use for width
 288  * @bbox: Bounding box to update
 289  * Return: 0 if OK, -ve on error
 290  */
 291 int scene_bbox_union(struct scene *scn, uint id, int inset,
 292                      struct vidconsole_bbox *bbox);
 293
 294 /**
 295  * scene_textline_calc_dims() - Calculate the dimensions of a textline
 296  *
 297  * Updates the width and height of the textline based on its contents
 298  *
 299  * @tline: Textline to update
 300  * Returns 0 if OK, -ENOTSUPP if there is no graphical console
 301  */
 302 int scene_textline_calc_dims(struct scene_obj_textline *tline);
 303
 304 /**
 305  * scene_menu_calc_bbox() - Calculate bounding boxes for the menu
 306  *
 307  * @menu: Menu to process
 308  * @bbox: Returns bounding box of menu including prompts
 309  * @label_bbox: Returns bounding box of labels
 310  * Return: 0 if OK, -ve on error
 311  */
 312 void scene_menu_calc_bbox(struct scene_obj_menu *menu,
 313                           struct vidconsole_bbox *bbox,
 314                           struct vidconsole_bbox *label_bbox);
 315
 316 /**
 317  * scene_textline_calc_bbox() - Calculate bounding box for the textline
 318  *
 319  * @textline: Menu to process
 320  * @bbox: Returns bounding box of textline including prompt
 321  * @edit_bbox: Returns bounding box of editable part
 322  * Return: 0 if OK, -ve on error
 323  */
 324 void scene_textline_calc_bbox(struct scene_obj_textline *menu,
 325                               struct vidconsole_bbox *bbox,
 326                               struct vidconsole_bbox *label_bbox);
 327
 328 /**
 329  * scene_obj_calc_bbox() - Calculate bounding boxes for an object
 330  *
 331  * @obj: Object to process
 332  * @bbox: Returns bounding box of object including prompts
 333  * @label_bbox: Returns bounding box of labels (active area)
 334  * Return: 0 if OK, -ve on error
 335  */
 336 int scene_obj_calc_bbox(struct scene_obj *obj, struct vidconsole_bbox *bbox,
 337                         struct vidconsole_bbox *label_bbox);
 338
 339 /**
 340  * scene_textline_open() - Open a textline object
 341  *
 342  * Set up the text editor ready for use
 343  *
 344  * @scn: Scene containing the textline
 345  * @tline: textline object
 346  * Return: 0 if OK, -ve on error
 347  */
 348 int scene_textline_open(struct scene *scn, struct scene_obj_textline *tline);
 349
 350 /**
 351  * scene_textline_close() - Close a textline object
 352  *
 353  * Close out the text editor after use
 354  *
 355  * @scn: Scene containing the textline
 356  * @tline: textline object
 357  * Return: 0 if OK, -ve on error
 358  */
 359 int scene_textline_close(struct scene *scn, struct scene_obj_textline *tline);
 360
 361 #endif /* __SCENE_INTERNAL_H */