grub-dev: Video API
10.1 Video API
==============
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'.
Info Catalog
grub-dev: Video Subsystem
grub-dev: Example usage of Video API