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 <[email protected]>
   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  * @arr: Arrangement information
 100  * @menu: Menu to process
 101  * Returns: 0 if OK, -ve on error
 102  */
 103 int scene_menu_arrange(struct scene *scn, struct expo_arrange_info *arr,
 104                        struct scene_obj_menu *menu);
 105
 106 /**
 107  * scene_textline_arrange() - Set the position of things in a textline
 108  *
 109  * This updates any items associated with a textline to make sure they are
 110  * positioned correctly relative to the textline.
 111  *
 112  * @scn: Scene to update
 113  * @arr: Arrangement information
 114  * @tline: textline to process
 115  * Returns: 0 if OK, -ve on error
 116  */
 117 int scene_textline_arrange(struct scene *scn, struct expo_arrange_info *arr,
 118                            struct scene_obj_textline *tline);
 119
 120 /**
 121  * scene_apply_theme() - Apply a theme to a scene
 122  *
 123  * @scn: Scene to update
 124  * @theme: Theme to apply
 125  * Returns: 0 if OK, -ve on error
 126  */
 127 int scene_apply_theme(struct scene *scn, struct expo_theme *theme);
 128
 129 /**
 130  * scene_menu_send_key() - Send a key to a menu for processing
 131  *
 132  * @scn: Scene to use
 133  * @menu: Menu to use
 134  * @key: Key code to send (KEY_...)
 135  * @event: Place to put any event which is generated by the key
 136  * Returns: 0 if OK, -ENOTTY if there is no current menu item, other -ve on other
 137  *      error
 138  */
 139 int scene_menu_send_key(struct scene *scn, struct scene_obj_menu *menu, int key,
 140                         struct expo_action *event);
 141
 142 /**
 143  * scene_textline_send_key() - Send a key to a textline for processing
 144  *
 145  * @scn: Scene to use
 146  * @tline: textline to use
 147  * @key: Key code to send (KEY_...)
 148  * @event: Place to put any event which is generated by the key
 149  * Returns: 0 if OK (always)
 150  */
 151 int scene_textline_send_key(struct scene *scn, struct scene_obj_textline *tline,
 152                             int key, struct expo_action *event);
 153
 154 /**
 155  * scene_menu_destroy() - Destroy a menu in a scene
 156  *
 157  * @scn: Scene to destroy
 158  */
 159 void scene_menu_destroy(struct scene_obj_menu *menu);
 160
 161 /**
 162  * scene_menu_display() - Display a menu as text
 163  *
 164  * @menu: Menu to display
 165  * Returns: 0 if OK, -ENOENT if @id is invalid
 166  */
 167 int scene_menu_display(struct scene_obj_menu *menu);
 168
 169 /**
 170  * scene_destroy() - Destroy a scene and all its memory
 171  *
 172  * @scn: Scene to destroy
 173  */
 174 void scene_destroy(struct scene *scn);
 175
 176 /**
 177  * scene_render() - Render a scene
 178  *
 179  * This is called from expo_render()
 180  *
 181  * @scn: Scene to render
 182  * Returns: 0 if OK, -ve on error
 183  */
 184 int scene_render(struct scene *scn);
 185
 186 /**
 187  * scene_send_key() - set a keypress to a scene
 188  *
 189  * @scn: Scene to receive the key
 190  * @key: Key to send (KEYCODE_UP)
 191  * @event: Returns resulting event from this keypress
 192  * Returns: 0 if OK, -ve on error
 193  */
 194 int scene_send_key(struct scene *scn, int key, struct expo_action *event);
 195
 196 /**
 197  * scene_render_deps() - Render an object and its dependencies
 198  *
 199  * @scn: Scene to render
 200  * @id: Object ID to render (or 0 for none)
 201  * Returns: 0 if OK, -ve on error
 202  */
 203 int scene_render_deps(struct scene *scn, uint id);
 204
 205 /**
 206  * scene_menu_render_deps() - Render a menu and its dependencies
 207  *
 208  * Renders the menu and all of its attached objects
 209  *
 210  * @scn: Scene to render
 211  * @menu: Menu to render
 212  * Returns: 0 if OK, -ve on error
 213  */
 214 int scene_menu_render_deps(struct scene *scn, struct scene_obj_menu *menu);
 215
 216 /**
 217  * scene_textline_render_deps() - Render a textline and its dependencies
 218  *
 219  * Renders the textline and all of its attached objects
 220  *
 221  * @scn: Scene to render
 222  * @tline: textline to render
 223  * Returns: 0 if OK, -ve on error
 224  */
 225 int scene_textline_render_deps(struct scene *scn,
 226                                struct scene_obj_textline *tline);
 227
 228 /**
 229  * scene_menu_calc_dims() - Calculate the dimensions of a menu
 230  *
 231  * Updates the width and height of the menu based on its contents
 232  *
 233  * @menu: Menu to update
 234  * Returns 0 if OK, -ENOTSUPP if there is no graphical console
 235  */
 236 int scene_menu_calc_dims(struct scene_obj_menu *menu);
 237
 238 /**
 239  * scene_iter_objs() - Iterate through all scene objects
 240  *
 241  * @scn: Scene to process
 242  * @iter: Iterator to call on each object
 243  * @priv: Private data to pass to the iterator, in addition to the object
 244  * Return: 0 if OK, -ve on error
 245  */
 246 int scene_iter_objs(struct scene *scn, expo_scene_obj_iterator iter,
 247                     void *priv);
 248
 249 /**
 250  * expo_iter_scene_objects() - Iterate through all scene objects
 251  *
 252  * @exp: Expo to process
 253  * @iter: Iterator to call on each object
 254  * @priv: Private data to pass to the iterator, in addition to the object
 255  * Return: 0 if OK, -ve on error
 256  */
 257 int expo_iter_scene_objs(struct expo *exp, expo_scene_obj_iterator iter,
 258                          void *priv);
 259
 260 /**
 261  * scene_menuitem_find() - Find the menu item for an ID
 262  *
 263  * Looks up the menu to find the item with the given ID
 264  *
 265  * @menu: Menu to check
 266  * @id: ID to look for
 267  * Return: Menu item, or NULL if not found
 268  */
 269 struct scene_menitem *scene_menuitem_find(const struct scene_obj_menu *menu,
 270                                           int id);
 271
 272 /**
 273  * scene_menuitem_find_seq() - Find the menu item at a sequential position
 274  *
 275  * This numbers the items from 0 and returns the seq'th one
 276  *
 277  * @menu: Menu to check
 278  * @seq: Sequence number to look for
 279  * Return: menu item if found, else NULL
 280  */
 281 struct scene_menitem *scene_menuitem_find_seq(const struct scene_obj_menu *menu,
 282                                               uint seq);
 283
 284 /**
 285  * scene_menuitem_find_val() - Find the menu item with a given value
 286  *
 287  * @menu: Menu to check
 288  * @find_val: Value to look for
 289  * Return: menu item if found, else NULL
 290  */
 291 struct scene_menitem *scene_menuitem_find_val(const struct scene_obj_menu *menu,
 292                                               int val);
 293
 294 /**
 295  * scene_bbox_union() - update bouding box with the demensions of an object
 296  *
 297  * Updates @bbox so that it encompasses the bounding box of object @id
 298  *
 299  * @snd: Scene containing object
 300  * @id: Object id
 301  * @inset: Amount of inset to use for width
 302  * @bbox: Bounding box to update
 303  * Return: 0 if OK, -ve on error
 304  */
 305 int scene_bbox_union(struct scene *scn, uint id, int inset,
 306                      struct vidconsole_bbox *bbox);
 307
 308 /**
 309  * scene_textline_calc_dims() - Calculate the dimensions of a textline
 310  *
 311  * Updates the width and height of the textline based on its contents
 312  *
 313  * @tline: Textline to update
 314  * Returns 0 if OK, -ENOTSUPP if there is no graphical console
 315  */
 316 int scene_textline_calc_dims(struct scene_obj_textline *tline);
 317
 318 /**
 319  * scene_menu_calc_bbox() - Calculate bounding boxes for the menu
 320  *
 321  * @menu: Menu to process
 322  * @bbox: Returns bounding box of menu including prompts
 323  * @label_bbox: Returns bounding box of labels
 324  * Return: 0 if OK, -ve on error
 325  */
 326 void scene_menu_calc_bbox(struct scene_obj_menu *menu,
 327                           struct vidconsole_bbox *bbox,
 328                           struct vidconsole_bbox *label_bbox);
 329
 330 /**
 331  * scene_textline_calc_bbox() - Calculate bounding box for the textline
 332  *
 333  * @textline: Menu to process
 334  * @bbox: Returns bounding box of textline including prompt
 335  * @edit_bbox: Returns bounding box of editable part
 336  * Return: 0 if OK, -ve on error
 337  */
 338 void scene_textline_calc_bbox(struct scene_obj_textline *menu,
 339                               struct vidconsole_bbox *bbox,
 340                               struct vidconsole_bbox *label_bbox);
 341
 342 /**
 343  * scene_obj_calc_bbox() - Calculate bounding boxes for an object
 344  *
 345  * @obj: Object to process
 346  * @bbox: Returns bounding box of object including prompts
 347  * @label_bbox: Returns bounding box of labels (active area)
 348  * Return: 0 if OK, -ve on error
 349  */
 350 int scene_obj_calc_bbox(struct scene_obj *obj, struct vidconsole_bbox *bbox,
 351                         struct vidconsole_bbox *label_bbox);
 352
 353 /**
 354  * scene_textline_open() - Open a textline object
 355  *
 356  * Set up the text editor ready for use
 357  *
 358  * @scn: Scene containing the textline
 359  * @tline: textline object
 360  * Return: 0 if OK, -ve on error
 361  */
 362 int scene_textline_open(struct scene *scn, struct scene_obj_textline *tline);
 363
 364 /**
 365  * scene_textline_close() - Close a textline object
 366  *
 367  * Close out the text editor after use
 368  *
 369  * @scn: Scene containing the textline
 370  * @tline: textline object
 371  * Return: 0 if OK, -ve on error
 372  */
 373 int scene_textline_close(struct scene *scn, struct scene_obj_textline *tline);
 374
 375 /**
 376  * scene_calc_arrange() - Calculate sizes needed to arrange a scene
 377  *
 378  * Checks the size of some objects and stores this info to help with a later
 379  * scene arrangement
 380  *
 381  * @scn: Scene to check
 382  * @arr: Place to put scene-arrangement info
 383  * Returns: 0 if OK, -ve on error
 384  */
 385 int scene_calc_arrange(struct scene *scn, struct expo_arrange_info *arr);
 386
 387 #endif /* __SCENE_INTERNAL_H */