Device Contexts


A device context is a device independent means of specifying graphics. A device context may be associated with a video display or a printer or other device. The functions that may be used for creating a new device context are shown in the table below.

begin_paint creates a device context suitable for painting a window.
get_device_context creates a display device context.
get_window_device_context creates a display device context for the entire window.
get_device_context_extended creates a display device context with clipping control.
create_device_context creates a device context suitable for printing.
create_memory_device_context creates a memory device context.
create_informational_device_context creates an information only device context.
create_metafile creates a metafile device context.

The first of these functions: begin_paint is usually called in response to the message message::paint. When the application is finished with such a device context, it should call end_paint to release the device context. This sequence creates a device context with attributes suitable for immediate drawing and validates the entire window (the invalid region of a window is the area marked as requiring painting). Drawing in a device context of this type implies that such drawing is clipped to the invalid region of the window. The rectangle found in the paint structure indicates the area to which drawing is restricted. Such a mechanism creates and destroys the device context within the body of the paint message.

The function get_device_context also creates a type of device context that is suitable for drawing in a window. Drawing is not clipped to the invalid region of the window, nor is any portion of the window validated for device contexts of this type. This type of device context is useful for drawing in a window in situations other than receiving a paint message. When finished with a device context of this type, the function release_device_context should be called.

The function get_device_context_extended creates a device context type that allows for clipping control. An application should use release_device_context to destroy device contexts of this type.

The function get_window_device_context creates a device context type that allows for drawing in the entire window - non-client areas included. applications generally use this type of device context rarely. Such a device context may be released via the function release_device_context.

The function create_device_context is the most general function that may be used to create a device context. It allows for the creation of device contexts associated with any device type, including screens and printers. For example, this function may be used to create a screen device context as shown below.

handle device_context = create_device_context("DISPLAY",0,0,0);

device contexts of this type are destroyed via the function delete_device_context.

The function create_informational_device_context creates a device context whose sole function is to query attributes of the associated device. device contexts of this type should be destroyed via a call to the function delete_device_context. An information device for the display may be created via the following call.

handle device_context = create_informational_device_context("DISPLAY",0,0,0);

A device context of type created via the function create_memory_device_context is used for storing bitmaps. When an application no longer requires a device context of this type, it should call the function delete_device_context.

A device context created via the function create_metafile is a metafile device context. This type of device context is destroyed via a call to the function close_metafile. Upon closing such a device context, a handle of the newly created metafile is returned.

Device Capabilities

The program of this section displays device capabilities. The output of the program is shown below.

The program consists of a source code file and a header file. The program resembles the programs of the previous chapter (a 3 column textual display) but the information is provided to display the capabilities of a device context. The header contains an array of values and descriptions of items to be drawn. The table includes the indices of the values to be queried and displayed.

The function get_device_capabilities is used to query the actual value of an index. The code sequence (that is part of the paint routine) that performs the query is shown below.

text_out(device_context,
        width_of_character + column1*width_of_capitals + column2*width_of_character,
        height_of_character * (i+1),
        buffer,
        print_string(buffer,"%5d",
                    get_device_capabilities(device_context,capabilities[i].index)));

The remaining portions of the program are taken up with displaying the information so gained via this method.

Colors

The function that queries device capabilities yields detailed information about the color capabilities of the device associated with a device context. color displays use more than 1 bit/pixel. In particular, the number of colors that may be displayed is 2bits/pixel. Sixteen color devices have 4 bits/pixel and are arranged in color planes. Such devices (VGA) have four color planes - a red plane, a green plane, a blue plane and an intensity plane. VGA devices are somewhat dated. Adapters with 8, 16 or 24 bits per pixel have a single color plane in which a number of adjacent bits are used to represent the color of each pixel.

The function get_device_capabilities allows for the determination of the organisation of memory in the video adapter and the number of colors that may be represented. The number of color planes may be queried using index capability::Planes; whereas, the number of bits per pixel may be queried via the index capability::BitsPixel. The number of supported colors may be directly queried via the index capability::Colors.

An unsigned integer is used to represent colors within a program. The data type that is used is shown below.

struct color
{
 unsigned Value;

 color(unsigned ValueSet=0) : Value(ValueSet) {}

 color(unsigned Red,
       unsigned Green,
       unsigned Blue) : Value(Red | Green << 8 | Blue << 16) {}

 color& operator=(unsigned ColorSet) {Value = ColorSet; return *this;}

 operator unsigned() const {return Value;}
};

The organisation of bits within the data type is depicted in the table below.

0 blue green red
31 ... 24 23 ... 16 15 ... 8 7 ... 0

An inline function exists to create a color from its parts and is shown below.

inline color red_green_blue(byte r, byte g, byte b)
{return ((color)(((byte)(r)|((unsigned char)((byte)(g))<<8))|(((unsigned)(byte)(b))<<16)));}

For example, the color magenta may be represented as red_green_blue(255,0,255) or more directly as 0xff00ff. The three inline functions that are available for extracting a particular color component from an unsigned integer are shown below.

inline byte RedValue(unsigned red_green_blue)   {return ((byte)(red_green_blue));}
inline byte GreenValue(unsigned red_green_blue) {return ((byte)(((unsigned char)(red_green_blue)) >> 8));}
inline byte BlueValue(unsigned red_green_blue)  {return ((byte)((red_green_blue)>>16));}

The following table shows several individual colors.

Value color
0x0000ff red
0x00ff00 green
0xff0000 blue
0x000000 Black
0xffffff White

Device Context attributes

device contexts have associated attributes. When a device context is first created, default values are applied for attributes. The following table documents device context attributes.

Attribute Default Value function to Set function to Query
unit mode unit::pixel set_mapping_mode get_mapping_mode
window Origin (0,0) set_window_origin
offset_window_origin
get_window_origin
Viewport Origin (0,0) set_viewport_origin
offset_viewport_origin
get_viewport_origin
window Extents (1,1) set_window_extent
scale_window_extent
set_mapping_mode
get_window_extent
Viewport Extents (1,1) set_viewport_extent
scale_viewport_extent
set_mapping_mode
get_viewport_extent
pen standard_pen::Black select_object get_current_object
brush standard_brush::White select_object get_current_object
font standard_font::System select_object get_current_object
bitmap none select_object get_current_object
position (0,0) move_to
draw_line_to
draw_lines_to
draw_splines_to
get_current_position
background mode background::Opaque set_background_mode get_background_mode
background color white set_background_color get_background_color
Text color black set_text_color get_text_color
Drawing mode mix::copyPen set_foreground_mix get_foreground_mix
Stretch mode stretch_block_mode::And set_stretch_bit_block_mode get_stretch_bit_block_mode
Filling mode fill_mode::Alternate set_fill_mode get_fill_mode
Extra Spacing 0 set_text_character_extra get_text_character_extra
brush Origin (0,0) set_brush_origin get_brush_origin
Clipping region none select_clipping_region
intersect_clipping_rectangle
offset_clipping_region
exclude_clipping_rectangle
exclude_update_region
select_clipping_path
get_clip_box

Saving and Restoring Device Context attributes

all of the attributes of a device context may be saved using the function save_device_context. Saved attributes may be later restored using the function restore_device_context.

Apart from this, when registering a window class, the class style class_style::own_device_context may be applied. When this style is applied, each window of the class has its own device context set aside. In this case, when a device context is created, destroyed and later recreated, it retains the most recent device context attributes.