GNU GRUB developer manual

10.1.1 grub_video_setup

• Prototype:

  grub_err_t
  grub_video_setup (unsigned int width, unsigned int height, unsigned int mode_type);
  

• Description:

  Driver will use information provided to it to select best possible video mode and switch to it. Supported values for mode_type are GRUB_VIDEO_MODE_TYPE_INDEX_COLOR for index color modes, GRUB_VIDEO_MODE_TYPE_RGB for direct RGB color modes and GRUB_VIDEO_MODE_TYPE_DOUBLE_BUFFERED for double buffering. When requesting RGB mode, highest bits per pixel mode will be selected. When requesting Index color mode, mode with highest number of colors will be selected. If all parameters are specified as zero, video adapter will try to figure out best possible mode and initialize it, platform specific differences are allowed here. If there is no mode matching request, error X will be returned. If there are no problems, function returns GRUB_ERR_NONE.

  This function also performs following task upon succesful mode switch. Active rendering target is changed to screen and viewport is maximized to allow whole screen to be used when performing graphics operations. In RGB modes, emulated palette gets 16 entries containing default values for VGA palette, other colors are defined as black. When switching to Indexed Color mode, driver may set default VGA palette to screen if the video card allows the operation.

10.1.2 grub_video_restore

• Prototype:

  grub_err_t
  grub_video_restore (void);
  

• Description:

  Video subsystem will deinitialize activated video driver to restore old state of video device. This can be used to switch back to text mode.

10.1.3 grub_video_get_info

• Prototype:

  grub_err_t
  grub_video_get_info (struct grub_video_mode_info *mode_info);
  

  struct grub_video_mode_info
  {
    /* Width of the screen.  */
    unsigned int width;
    /* Height of the screen.  */
    unsigned int height;
    /* Mode type bitmask.  Contains information like is it Index color or
       RGB mode.  */
    unsigned int mode_type;
    /* Bits per pixel.  */
    unsigned int bpp;
    /* Bytes per pixel.  */
    unsigned int bytes_per_pixel;
    /* Pitch of one scanline.  How many bytes there are for scanline.  */
    unsigned int pitch;
    /* In index color mode, number of colors.  In RGB mode this is 256.  */
    unsigned int number_of_colors;
    /* Optimization hint how binary data is coded.  */
    enum grub_video_blit_format blit_format;
    /* How many bits are reserved for red color.  */
    unsigned int red_mask_size;
    /* What is location of red color bits.  In Index Color mode, this is 0.  */
    unsigned int red_field_pos;
    /* How many bits are reserved for green color.  */
    unsigned int green_mask_size;
    /* What is location of green color bits.  In Index Color mode, this is 0.  */
    unsigned int green_field_pos;
    /* How many bits are reserved for blue color.  */
    unsigned int blue_mask_size;
    /* What is location of blue color bits.  In Index Color mode, this is 0.  */
    unsigned int blue_field_pos;
    /* How many bits are reserved in color.  */
    unsigned int reserved_mask_size;
    /* What is location of reserved color bits.  In Index Color mode,
       this is 0.  */
    unsigned int reserved_field_pos;
  };
  

• Description:

  Software developer can use this function to query properties of active rendering taget. Information provided here can be used by other parts of GRUB, like image loaders to convert loaded images to correct screen format to allow more optimized blitters to be used. If there there is no configured video driver with active screen, error GRUB_ERR_BAD_DEVICE is returned, otherwise mode_info is filled with valid information and GRUB_ERR_NONE is returned.

10.1.4 grub_video_get_blit_format

• Prototype:

  enum grub_video_blit_format
  grub_video_get_blit_format (struct grub_video_mode_info *mode_info);
  

  enum grub_video_blit_format
    {
      /* Follow exactly field & mask information.  */
      GRUB_VIDEO_BLIT_FORMAT_RGBA,
      /* Make optimization assumption.  */
      GRUB_VIDEO_BLIT_FORMAT_R8G8B8A8,
      /* Follow exactly field & mask information.  */
      GRUB_VIDEO_BLIT_FORMAT_RGB,
      /* Make optimization assumption.  */
      GRUB_VIDEO_BLIT_FORMAT_R8G8B8,
      /* When needed, decode color or just use value as is.  */
      GRUB_VIDEO_BLIT_FORMAT_INDEXCOLOR
    };
  

• Description:

  Used to query how data could be optimized to suit specified video mode. Returns exact video format type, or a generic one if there is no definition for the type. For generic formats, use grub_video_get_info to query video color coding settings.

10.1.5 grub_video_set_palette

• Prototype:

  grub_err_t
  grub_video_set_palette (unsigned int start, unsigned int count, struct grub_video_palette_data *palette_data);
  

  struct grub_video_palette_data
  {
      grub_uint8_t r; /* Red color value (0-255). */
      grub_uint8_t g; /* Green color value (0-255). */
      grub_uint8_t b; /* Blue color value (0-255). */
      grub_uint8_t a; /* Reserved bits value (0-255). */
  };
  

• Description:

  Used to setup indexed color palettes. If mode is RGB mode, colors will be set to emulated palette data. In Indexed Color modes, palettes will be set to hardware. Color values will be converted to suit requirements of the video mode. start will tell what hardware color index (or emulated color index) will be set to according information in first indice of palette_data, after that both hardware color index and palette_data index will be incremented until count number of colors have been set.

10.1.6 grub_video_get_palette

• Prototype:

  grub_err_t
  grub_video_get_palette (unsigned int start, unsigned int count, struct grub_video_palette_data *palette_data);
  

  struct grub_video_palette_data
  {
      grub_uint8_t r; /* Red color value (0-255). */
      grub_uint8_t g; /* Green color value (0-255). */
      grub_uint8_t b; /* Blue color value (0-255). */
      grub_uint8_t a; /* Reserved bits value (0-255). */
  };
  

• Description:

  Used to query indexed color palettes. If mode is RGB mode, colors will be copied from emulated palette data. In Indexed Color modes, palettes will be read from hardware. Color values will be converted to suit structure format. start will tell what hardware color index (or emulated color index) will be used as a source for first indice of palette_data, after that both hardware color index and palette_data index will be incremented until count number of colors have been read.

10.1.7 grub_video_set_area_status

• Prototype:

  grub_err_t
  grub_video_set_area_status (grub_video_area_status_t area_status);
  

  enum grub_video_area_status_t
    {
      GRUB_VIDEO_AREA_DISABLED,
      GRUB_VIDEO_AREA_ENABLED
    };
  

• Description:

  Used to set area drawing mode for redrawing the specified region. Draw commands are performed in the intersection of the viewport and the region called area. Coordinates remain related to the viewport. If draw commands try to draw over the area, they are clipped. Set status to DISABLED if you need to draw everything. Set status to ENABLED and region to the desired rectangle to redraw everything inside the region leaving everything else intact. Should be used for redrawing of active elements.

10.1.8 grub_video_get_area_status

• Prototype:

  grub_err_r
  grub_video_get_area_status (grub_video_area_status_t *area_status);
  

• Description: Used to query the area status.

10.1.9 grub_video_set_viewport

• Prototype:

  grub_err_t
  grub_video_set_viewport (unsigned int x, unsigned int y, unsigned int width, unsigned int height);
  

• Description:

  Used to specify viewport where draw commands are performed. When viewport is set, all draw commands coordinates relate to those specified by x and y. If draw commands try to draw over viewport, they are clipped. If developer requests larger than possible viewport, width and height will be clamped to fit screen. If x and y are out of bounds, all functions drawing to screen will not be displayed. In order to maximize viewport, use grub_video_get_info to query actual screen dimensions and provide that information to this function.

10.1.10 grub_video_get_viewport

• Prototype:

  grub_err_t
  grub_video_get_viewport (unsigned int *x, unsigned int *y, unsigned int *width, unsigned int *height);
  

• Description:

  Used to query current viewport dimensions. Software developer can use this to choose best way to render contents of the viewport.

10.1.11 grub_video_set_region

• Prototype:

  grub_err_t
  grub_video_set_region (unsigned int x, unsigned int y, unsigned int width, unsigned int height);
  

• Description:

  Used to specify the region of the screen which should be redrawn. Use absolute values. When the region is set and area status is ENABLE all draw commands will be performed inside the interseption of region and viewport named area. If draw commands try to draw over viewport, they are clipped. If developer requests larger than possible region, width and height will be clamped to fit screen. Should be used for redrawing of active elements.

10.1.12 grub_video_get_region

• Prototype:

  grub_err_t
  grub_video_get_region (unsigned int *x, unsigned int *y, unsigned int *width, unsigned int *height);
  

• Description:

  Used to query current region dimensions.

10.1.13 grub_video_map_color

• Prototype:

  grub_video_color_t
  grub_video_map_color (grub_uint32_t color_name);
  

• Description:

  Map color can be used to support color themes in GRUB. There will be collection of color names that can be used to query actual screen mapped color data. Examples could be GRUB_COLOR_CONSOLE_BACKGROUND, GRUB_COLOR_CONSOLE_TEXT. The actual color defines are not specified at this point.

10.1.14 grub_video_map_rgb

• Prototype:

  grub_video_color_t
  grub_video_map_rgb (grub_uint8_t red, grub_uint8_t green, grub_uint8_t blue);
  

• Description:

  Map RGB values to compatible screen color data. Values are expected to be in range 0-255 and in RGB modes they will be converted to screen color data. In index color modes, index color palette will be searched for specified color and then index is returned.

10.1.15 grub_video_map_rgba

• Prototype:

  grub_video_color_t
  grub_video_map_rgba (grub_uint8_t red, grub_uint8_t green, grub_uint8_t blue, grub_uint8_t alpha);
  

• Description:

  Map RGBA values to compatible screen color data. Values are expected to be in range 0-255. In RGBA modes they will be converted to screen color data. In index color modes, index color palette will be searched for best matching color and its index is returned.

10.1.16 grub_video_unmap_color

• Prototype:

  grub_err_t
  grub_video_unmap_color (grub_video_color_t color, grub_uint8_t *red, grub_uint8_t *green, grub_uint8_t *blue, grub_uint8_t *alpha);
  

• Description:

  Unmap color value from color to color channels in red, green, blue and alpha. Values will be in range 0-255. Active rendering target will be used for color domain. In case alpha information is not available in rendering target, it is assumed to be opaque (having value 255).

10.1.17 grub_video_fill_rect

• Prototype:

  grub_err_t
  grub_video_fill_rect (grub_video_color_t color, int x, int y, unsigned int width, unsigned int height);
  

• Description:

  Fill specified area limited by given coordinates within specified viewport. Negative coordinates are accepted in order to allow easy moving of rectangle within viewport. If coordinates are negative, area of the rectangle will be shrinken to follow size limits of the viewport.

  Software developer should use either grub_video_map_color, grub_video_map_rgb or grub_video_map_rgba to map requested color to color parameter.

10.1.18 grub_video_blit_glyph

• Prototype:

  grub_err_t
  grub_video_blit_glyph (struct grub_font_glyph *glyph, grub_video_color_t color, int x, int y);
  

  struct grub_font_glyph {
      /* TBD. */
  };
  

• Description:

  Used to blit glyph to viewport in specified coodinates. If glyph is at edge of viewport, pixels outside of viewport will be clipped out. Software developer should use either grub_video_map_rgb or grub_video_map_rgba to map requested color to color parameter.

10.1.19 grub_video_blit_bitmap

• Prototype:

  grub_err_t
  grub_video_blit_bitmap (struct grub_video_bitmap *bitmap, enum grub_video_blit_operators oper, int x, int y, int offset_x, int offset_y, unsigned int width, unsigned int height);
  

  struct grub_video_bitmap
  {
      /* TBD. */
  };
  
  enum grub_video_blit_operators
    {
      GRUB_VIDEO_BLIT_REPLACE,
      GRUB_VIDEO_BLIT_BLEND
    };
  

• Description:

  Used to blit bitmap to viewport in specified coordinates. If part of bitmap is outside of viewport region, it will be clipped out. Offsets affect bitmap position where data will be copied from. Negative values for both viewport coordinates and bitmap offset coordinates are allowed. If data is looked out of bounds of bitmap, color value will be assumed to be transparent. If viewport coordinates are negative, area of the blitted rectangle will be shrinken to follow size limits of the viewport and bitmap. Blitting operator oper specifies should source pixel replace data in screen or blend with pixel alpha value.

  Software developer should use grub_video_bitmap_create or grub_video_bitmap_load to create or load bitmap data.

10.1.20 grub_video_blit_render_target

• Prototype:

  grub_err_t
  grub_video_blit_render_target (struct grub_video_render_target *source, enum grub_video_blit_operators oper, int x, int y, int offset_x, int offset_y, unsigned int width, unsigned int height);
  

  struct grub_video_render_target {
      /* This is private data for video driver. Should not be accessed from elsewhere directly.  */
  };
  
  enum grub_video_blit_operators
    {
      GRUB_VIDEO_BLIT_REPLACE,
      GRUB_VIDEO_BLIT_BLEND
    };
  

• Description:

  Used to blit source render target to viewport in specified coordinates. If part of source render target is outside of viewport region, it will be clipped out. If blitting operator is specified and source contains alpha values, resulting pixel color components will be calculated using formula ((src_color * src_alpha) + (dst_color * (255 - src_alpha)) / 255, if target buffer has alpha, it will be set to src_alpha. Offsets affect render target position where data will be copied from. If data is looked out of bounds of render target, color value will be assumed to be transparent. Blitting operator oper specifies should source pixel replace data in screen or blend with pixel alpha value.

10.1.21 grub_video_scroll

• Prototype:

  grub_err_t
  grub_video_scroll (grub_video_color_t color, int dx, int dy);
  

• Description:

  Used to scroll viewport to specified direction. New areas are filled with specified color. This function is used when screen is scroller up in video terminal.

10.1.22 grub_video_swap_buffers

• Prototype:

  grub_err_t
  grub_video_swap_buffers (void);
  

• Description:

  If double buffering is enabled, this swaps frontbuffer and backbuffer, in order to show values drawn to back buffer. Video driver is free to choose how this operation is techincally done.

10.1.23 grub_video_create_render_target

• Prototype:

  grub_err_t
  grub_video_create_render_target (struct grub_video_render_target **result, unsigned int width, unsigned int height, unsigned int mode_type);
  

  struct grub_video_render_target {
      /* This is private data for video driver. Should not be accessed from elsewhere directly.  */
  };
  

• Description:

  Driver will use information provided to it to create best fitting render target. mode_type will be used to guide on selecting what features are wanted for render target. Supported values for mode_type are GRUB_VIDEO_MODE_TYPE_INDEX_COLOR for index color modes, GRUB_VIDEO_MODE_TYPE_RGB for direct RGB color modes and GRUB_VIDEO_MODE_TYPE_ALPHA for alpha component.

10.1.24 grub_video_delete_render_target

• Prototype:

  grub_err_t
  grub_video_delete_render_target (struct grub_video_render_target *target);
  

• Description:

  Used to delete previously created render target. If target contains NULL pointer, nothing will be done. If render target is correctly destroyed, GRUB_ERR_NONE is returned.

10.1.25 grub_video_set_active_render_target

• Prototype:

  grub_err_t
  grub_video_set_active_render_target (struct grub_video_render_target *target);
  

• Description:

  Sets active render target. If this comand is successful all drawing commands will be done to specified target. There is also special values for target, GRUB_VIDEO_RENDER_TARGET_DISPLAY used to reference screen’s front buffer, GRUB_VIDEO_RENDER_TARGET_FRONT_BUFFER used to reference screen’s front buffer (alias for GRUB_VIDEO_RENDER_TARGET_DISPLAY) and GRUB_VIDEO_RENDER_TARGET_BACK_BUFFER used to reference back buffer (if double buffering is enabled). If render target is correclty switched GRUB_ERR_NONE is returned. In no any event shall there be non drawable active render target.

10.1.26 grub_video_get_active_render_target

• Prototype:

  grub_err_t
  grub_video_get_active_render_target (struct grub_video_render_target **target);
  

• Description:

  Returns currently active render target. It returns value in target that can be subsequently issued back to grub_video_set_active_render_target.

10.2.1 Example of screen setup

grub_err_t rc;
/* Try to initialize video mode 1024 x 768 with direct RGB.  */
rc = grub_video_setup (1024, 768, GRUB_VIDEO_MODE_TYPE_RGB);
if (rc != GRUB_ERR_NONE)
{
  /* Fall back to standard VGA Index Color mode.  */
  rc = grub_video_setup (640, 480, GRUB_VIDEO_MODE_TYPE_INDEX);
  if (rc != GRUB_ERR_NONE)
  {
  /* Handle error.  */
  }
}

10.2.2 Example of setting up console viewport

grub_uint32_t x, y, width, height;
grub_video_color_t color;
struct grub_font_glyph glyph;
grub_err_t rc;
/* Query existing viewport.  */
grub_video_get_viewport (&x, &y, &width, &height);
/* Fill background.  */
color = grub_video_map_color (GRUB_COLOR_BACKGROUND);
grub_video_fill_rect (color, 0, 0, width, height);
/* Setup console viewport.  */
grub_video_set_viewport (x + 10, y + 10, width - 20, height - 20);
grub_video_get_viewport (&x, &y, &width, &height);
color = grub_video_map_color (GRUB_COLOR_CONSOLE_BACKGROUND);
grub_video_fill_rect (color, 0, 0, width, height);
/* Draw text to viewport.  */
color = grub_video_map_color (GRUB_COLOR_CONSOLE_TEXT);
grub_font_get_glyph ('X', &glyph);
grub_video_blit_glyph (&glyph, color, 0, 0);

10.3.1 grub_video_bitmap_create

• Prototype:

  grub_err_t grub_video_bitmap_create (struct grub_video_bitmap **bitmap, unsigned int width, unsigned int height, enum grub_video_blit_format blit_format)
  

• Description:

  Creates a new bitmap with given dimensions and blitting format. Allocated bitmap data can then be modified freely and finally blitted with grub_video_blit_bitmap to rendering target.

10.3.2 grub_video_bitmap_destroy

• Prototype:

  grub_err_t grub_video_bitmap_destroy (struct grub_video_bitmap *bitmap);
  

• Description:

  When bitmap is no longer needed, it can be freed from memory using this command. bitmap is previously allocated bitmap with grub_video_bitmap_create or loaded with grub_video_bitmap_load.

10.3.3 grub_video_bitmap_load

• Prototype:

  grub_err_t grub_video_bitmap_load (struct grub_video_bitmap **bitmap, const char *filename);
  

• Description:

  Tries to load given bitmap (filename) using registered bitmap loaders. In case bitmap format is not recognized or supported error GRUB_ERR_BAD_FILE_TYPE is returned.

10.3.4 grub_video_bitmap_get_width

• Prototype:

  unsigned int grub_video_bitmap_get_width (struct grub_video_bitmap *bitmap);
  

• Description:

  Returns bitmap width.

10.3.5 grub_video_bitmap_get_height

• Prototype:

  unsigned int grub_video_bitmap_get_height (struct grub_video_bitmap *bitmap);
  

• Description:

  Return bitmap height.

10.3.6 grub_video_bitmap_get_mode_info

• Prototype:

  void grub_video_bitmap_get_mode_info (struct grub_video_bitmap *bitmap, struct grub_video_mode_info *mode_info);
  

• Description:

  Returns bitmap format details in form of grub_video_mode_info.

10.3.7 grub_video_bitmap_get_data

• Prototype:

  void *grub_video_bitmap_get_data (struct grub_video_bitmap *bitmap);
  

• Description:

  Return pointer to bitmap data. Contents of the pointed data can be freely modified. There is no extra protection against going off the bounds so you have to be carefull how to access the data.

11.1.1 Goals of the GRUB Font Format

• Simple to read and use. Since GRUB will only be reading the font files, we are more concerned with making the code to read the font simple than we are with writing the font.
• Compact storage. The fonts will generally be stored in a small boot partition where GRUB is located, and this may be on a removable storage device such as a CD or USB flash drive where space is more limited than it is on most hard drives.
• Unicode. GRUB should not have to deal with multiple character encodings. The font should always use Unicode character codes for simple internationalization.

11.1.2 Why Another Font Format?

There are many existing bitmap font formats that GRUB could use. However, there are aspects of these formats that may make them less than suitable for use in GRUB at this time:

‘BDF’

Inefficient storage; uses ASCII to describe properties and hexadecimal numbers in ASCII for the bitmap rows.

‘PCF’

Many format variations such as byte order and bitmap padding (rows padded to byte, word, etc.) would result in more complex code to handle the font format.

11.2.1 Section Types

‘FILE’

File type ID (ASCII string). This must be the first section in the file. It has length 4 and the contents are the four bytes of the ASCII string ‘PFF2’.

‘NAME’

Font name (ASCII string). This is the full font name including family, weight, style, and point size. For instance, "Helvetica Bold Italic 14".

‘FAMI’

Font family name (ASCII string). For instance, "Helvetica". This should be included so that intelligent font substitution can take place.

‘WEIG’

Font weight (ASCII string). Valid values are ‘bold’ and ‘normal’. This should be included so that intelligent font substitution can take place.

‘SLAN’

Font slant (ASCII string). Valid values are ‘italic’ and ‘normal’. This should be included so that intelligent font substitution can take place.

‘PTSZ’

Font point size (uint16be).

‘MAXW’

Maximum character width in pixels (uint16be).

‘MAXH’

Maximum character height in pixels (uint16be).

‘ASCE’

Ascent in pixels (uint16be). See Font Metrics, for details.

‘DESC’

Descent in pixels (uint16be). See Font Metrics, for details.

‘CHIX’

Character index. The character index begins with a 32-bit big-endian unsigned integer indicating the total size of the section, not including this size value. For each character, there is an instance of the following entry structure:

• Unicode code point. (32-bit big-endian integer.)
• Storage flags. (byte.)
  • Bits 2..0:

    If equal to 000 binary, then the character data is stored uncompressed beginning at the offset indicated by the character’s offset value.

    If equal to 001 binary, then the character data is stored within a compressed character definition block that begins at the offset within the file indicated by the character’s offset value.

• Offset. (32-bit big-endian integer.)

  A marker that indicates the remainder of the file is data accessed via the character index (CHIX) section. When reading this font file, the rest of the file can be ignored when scanning the sections. The length should be set to -1 (0xFFFFFFFF).

  Supported data structures:

  Character definition Each character definition consists of:

  • Width. Width of the bitmap in pixels. The bitmap’s extents represent the glyph’s bounding box. uint16be.
  • Height. Height of the bitmap in pixels. The bitmap’s extents represent the glyph’s bounding box. uint16be.
  • X offset. The number of pixels to shift the bitmap by horizontally before drawing the character. int16be.
  • Y offset. The number of pixels to shift the bitmap by vertically before drawing the character. int16be.
  • Device width. The number of pixels to advance horizontally from this character’s origin to the origin of the next character. int16be.
  • Bitmap data. This is encoded as a string of bits. It is organized as a row-major, top-down, left-to-right bitmap. The most significant bit of each byte is taken to be the leftmost or uppermost bit in the byte. For the sake of compact storage, rows are not padded to byte boundaries (i.e., a single byte may contain bits belonging to multiple rows). The last byte of the bitmap is padded with zero bits in the bits positions to the right of the last used bit if the bitmap data does not fill the last byte.

    The length of the bitmap data field is (width * height + 7) / 8 using integer arithmetic, which is equivalent to ceil(width * height / 8) using real number arithmetic.

    It remains to be determined whether bitmap fonts usually make all glyph bitmaps the same height, or if smaller glyphs are stored with bitmaps having a lesser height. In the latter case, the baseline would have to be used to calculate the location the bitmap should be anchored at on screen.