Next: Example usage of Video API, Up: Video Subsystem [Contents][Index]
grub_err_t grub_video_setup (unsigned int width, unsigned int height, unsigned int mode_type);
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.
grub_err_t grub_video_restore (void);
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_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;
};
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.
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
};
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_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). */
};
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_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). */
};
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_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
};
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.
grub_err_r grub_video_get_area_status (grub_video_area_status_t *area_status);
grub_err_t grub_video_set_viewport (unsigned int x, unsigned int y, unsigned int width, unsigned int height);
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_err_t grub_video_get_viewport (unsigned int *x, unsigned int *y, unsigned int *width, unsigned int *height);
Used to query current viewport dimensions. Software developer can use this to choose best way to render contents of the viewport.
grub_err_t grub_video_set_region (unsigned int x, unsigned int y, unsigned int width, unsigned int height);
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.
grub_err_t grub_video_get_region (unsigned int *x, unsigned int *y, unsigned int *width, unsigned int *height);
Used to query current region dimensions.
grub_video_color_t grub_video_map_color (grub_uint32_t color_name);
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_color_t grub_video_map_rgb (grub_uint8_t red, grub_uint8_t green, grub_uint8_t blue);
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.
grub_video_color_t grub_video_map_rgba (grub_uint8_t red, grub_uint8_t green, grub_uint8_t blue, grub_uint8_t alpha);
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.
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);
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_err_t grub_video_fill_rect (grub_video_color_t color, int x, int y, unsigned int width, unsigned int height);
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_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. */
};
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_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
};
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_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
};
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_err_t grub_video_scroll (grub_video_color_t color, int dx, int dy);
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_err_t grub_video_swap_buffers (void);
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_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. */
};
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_err_t grub_video_delete_render_target (struct grub_video_render_target *target);
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_err_t grub_video_set_active_render_target (struct grub_video_render_target *target);
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.
grub_err_t grub_video_get_active_render_target (struct grub_video_render_target **target);
Returns currently active render target. It returns value in target that can be subsequently issued back to grub_video_set_active_render_target.
Next: Example usage of Video API, Up: Video Subsystem [Contents][Index]