• VideoSubsystem

GRUB 2 - Video Subsystem

Introduction

This document contains specification for Video Subsystem for GRUB2. Currently only the usage interface is described in this document. Internal structure of how video drivers are registering and how video driver manager works are not included here.

Video API

grub_video_setup

Prototype:

   1 grub_err_t
   2 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 get's 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.

grub_video_restore

Prototype:

   1 grub_err_t
   2 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.

grub_video_get_info

Prototype:

   1 grub_err_t
   2 grub_video_get_info (struct grub_video_mode_info *mode_info);

   1 struct grub_video_mode_info
   2 {
   3   /* Width of the screen.  */
   4   unsigned int width;
   5   /* Height of the screen.  */
   6   unsigned int height;
   7   /* Mode type bitmask.  Contains information like is it Index color or
   8      RGB mode.  */
   9   unsigned int mode_type;
  10   /* Bits per pixel.  */
  11   unsigned int bpp;
  12   /* Bytes per pixel.  */
  13   unsigned int bytes_per_pixel;
  14   /* Pitch of one scanline.  How many bytes there are for scanline.  */
  15   unsigned int pitch;
  16   /* In index color mode, number of colors.  In RGB mode this is 256.  */
  17   unsigned int number_of_colors;
  18   /* Optimization hint how binary data is coded.  */
  19   enum grub_video_blit_format blit_format;
  20   /* How many bits are reserved for red color.  */
  21   unsigned int red_mask_size;
  22   /* What is location of red color bits.  In Index Color mode, this is 0.  */
  23   unsigned int red_field_pos;
  24   /* How many bits are reserved for green color.  */
  25   unsigned int green_mask_size;
  26   /* What is location of green color bits.  In Index Color mode, this is 0.  */
  27   unsigned int green_field_pos;
  28   /* How many bits are reserved for blue color.  */
  29   unsigned int blue_mask_size;
  30   /* What is location of blue color bits.  In Index Color mode, this is 0.  */
  31   unsigned int blue_field_pos;
  32   /* How many bits are reserved in color.  */
  33   unsigned int reserved_mask_size;
  34   /* What is location of reserved color bits.  In Index Color mode,
  35      this is 0.  */
  36   unsigned int reserved_field_pos;
  37 };

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.

grub_video_get_blit_format

Prototype:

   1 enum grub_video_blit_format
   2 grub_video_get_blit_format (struct grub_video_mode_info *mode_info);

   1 enum grub_video_blit_format
   2   {
   3     /* Follow exactly field & mask information.  */
   4     GRUB_VIDEO_BLIT_FORMAT_RGBA,
   5     /* Make optimization assumption.  */
   6     GRUB_VIDEO_BLIT_FORMAT_R8G8B8A8,
   7     /* Follow exactly field & mask information.  */
   8     GRUB_VIDEO_BLIT_FORMAT_RGB,
   9     /* Make optimization assumption.  */
  10     GRUB_VIDEO_BLIT_FORMAT_R8G8B8,
  11     /* When needed, decode color or just use value as is.  */
  12     GRUB_VIDEO_BLIT_FORMAT_INDEXCOLOR
  13   };

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.

grub_video_set_palette

Prototype:

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

   1 struct grub_video_palette_data
   2 {
   3     grub_uint8_t r; /* Red color value (0-255). */
   4     grub_uint8_t g; /* Green color value (0-255). */
   5     grub_uint8_t b; /* Blue color value (0-255). */
   6     grub_uint8_t a; /* Reserved bits value (0-255). */
   7 };

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.

grub_video_get_palette

Prototype:

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

   1 struct grub_video_palette_data
   2 {
   3     grub_uint8_t r; /* Red color value (0-255). */
   4     grub_uint8_t g; /* Green color value (0-255). */
   5     grub_uint8_t b; /* Blue color value (0-255). */
   6     grub_uint8_t a; /* Reserved bits value (0-255). */
   7 };

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.

grub_video_set_viewport

Prototype:

   1 grub_err_t
   2 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.

grub_video_get_viewport

Prototype:

   1 grub_err_t
   2 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.

grub_video_map_color

Prototype:

   1 grub_video_color_t
   2 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.

grub_video_map_rgb

Prototype:

   1 grub_video_color_t
   2 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 excepted 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.

grub_video_map_rgba

Prototype:

   1 grub_video_color_t
   2 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 excepted 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 it's index is returned.

grub_video_unmap_color

Prototype:

   1 grub_err_t
   2 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).

grub_video_fill_rect

Prototype:

   1 grub_err_t
   2 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.

grub_video_blit_glyph

Prototype:

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

   1 struct grub_font_glyph {
   2     /* TBD. */
   3 };

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.

grub_video_blit_bitmap

Prototype:

   1 grub_err_t
   2 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);

   1 struct grub_video_bitmap
   2 {
   3     /* TBD. */
   4 };
   5 
   6 enum grub_video_blit_operators
   7   {
   8     GRUB_VIDEO_BLIT_REPLACE,
   9     GRUB_VIDEO_BLIT_BLEND
  10   };

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.

grub_video_blit_render_target

Prototype:

   1 grub_err_t
   2 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);

   1 struct grub_video_render_target {
   2     /* This is private data for video driver. Should not be accessed from elsewhere directly.  */
   3 };
   4 
   5 enum grub_video_blit_operators
   6   {
   7     GRUB_VIDEO_BLIT_REPLACE,
   8     GRUB_VIDEO_BLIT_BLEND
   9   };

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.

grub_video_scroll

Prototype:

   1 grub_err_t
   2 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.

grub_video_swap_buffers

Prototype:

   1 grub_err_t
   2 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.

grub_video_create_render_target

Prototype:

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

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

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.

grub_video_delete_render_target

Prototype:

   1 grub_err_t
   2 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.

grub_video_set_active_render_target

Prototype:

   1 grub_err_t
   2 grub_video_set_active_render_target (struct grub_video_render_target *target);

Description:

Set's 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.

grub_video_get_active_render_target

Prototype:

   1 grub_err_t
   2 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.

Example usage of Video API

Example of screen setup

   1 grub_err_t rc;
   2 /* Try to initialize video mode 1024 x 768 with direct RGB.  */
   3 rc = grub_video_setup (1024, 768, GRUB_VIDEO_MODE_TYPE_RGB);
   4 if (rc != GRUB_ERR_NONE)
   5 {
   6   /* Fall back to standard VGA Index Color mode.  */
   7   rc = grub_video_setup (640, 480, GRUB_VIDEO_MODE_TYPE_INDEX);
   8   if (rc != GRUB_ERR_NONE)
   9   {
  10   /* Handle error.  */
  11   }
  12 }

Example of setting up console viewport

   1 grub_uint32_t x, y, width, height;
   2 grub_video_color_t color;
   3 struct grub_font_glyph glyph;
   4 grub_err_t rc;
   5 /* Query existing viewport.  */
   6 grub_video_get_viewport (&x, &y, &width, &height);
   7 /* Fill background.  */
   8 color = grub_video_map_color (GRUB_COLOR_BACKGROUND);
   9 grub_video_fill_rect (color, 0, 0, width, height);
  10 /* Setup console viewport.  */
  11 grub_video_set_viewport (x + 10, y + 10, width - 20, height - 20);
  12 grub_video_get_viewport (&x, &y, &width, &height);
  13 color = grub_video_map_color (GRUB_COLOR_CONSOLE_BACKGROUND);
  14 grub_video_fill_rect (color, 0, 0, width, height);
  15 /* Draw text to viewport.  */
  16 color = grub_video_map_color (GRUB_COLOR_CONSOLE_TEXT);
  17 grub_font_get_glyph ('X', &glyph);
  18 grub_video_blit_glyph (&glyph, color, 0, 0);

Bitmap API

grub_video_bitmap_create

Prototype:

   1 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.

grub_video_bitmap_destroy

Prototype:

   1 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.

grub_video_bitmap_load

Prototype:

   1 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.

grub_video_bitmap_get_width

Prototype:

   1 unsigned int grub_video_bitmap_get_width (struct grub_video_bitmap *bitmap);

Description:

Returns bitmap width.

grub_video_bitmap_get_height

Prototype:

   1 unsigned int grub_video_bitmap_get_height (struct grub_video_bitmap *bitmap);

Description:

Return bitmap height.

grub_video_bitmap_get_mode_info

Prototype:

   1 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.

grub_video_bitmap_get_data

Prototype:

   1 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.

Other changes needed for GRUB 2

Font Manager needs to be changed to support better handling for Glyphs. In order to support larger amount of character types, someone needs to design portable glyph format.

Idea for new grub_font_glyph structure:

   1 struct grub_font_glyph
   2 {
   3   /* Glyph width in pixels.  */
   4   grub_uint8_t width;
   5   /* Glyph height in pixels.  */
   6   grub_uint8_t height;
   7   /* Glyph width in characters.  */
   8   grub_uint8_t char_width;
   9   /* Glyph baseline position in pixels (from up).  */
  10   grub_uint8_t baseline;
  11   /* Glyph bitmap data array of bytes in ((width + 7) / 8) * height.
  12      Bitmap is formulated by height scanlines, each scanline having
  13      width number of pixels. Pixels are coded as bits, value 1 meaning
  14      of opaque pixel and 0 is transparent. If width does not fit byte
  15      boundary, it will be padded with 0 to make it fit.  */
  16   grub_uint8_t bitmap[32];
  17 };

CategoryDeveloper