class HT_Renderer

class HT_Renderer

This is the base class for all renderers including physical renderers such as device drivers as well as specialized renderers such as software Z-buffer renderers. The HT_Renderer object provides methods for drawing objects to a display or plotter through the member functions of HT_Renderer object. The class provides methods for drawing objects of differing geometric complexities such as dots, polylines, polygons, polytriangles, ellipses, tristrips, and others. Methods to draw objects at 3D, 2D, or device coordinates also exist.

Each 3D drawing method defines a primitive of a certain geometric type. Each method takes a geometry descriptor argument and a rendition argument. All of the 3D geometry descriptors specify the kind of geometry (by their class) and the specific instance of the geometry through a set of vertices which places the geometric object in object coordinates. These vertices are subject to the 3D transformation pipeline, specified in the rendition argument. The geometry descriptors for the "strip" primitives also may specify colors and/or normal vectors attached to faces and/or vertices, to be used in calculating the effects of lighting and shading.

For each of the following draw_2d_... primitives there is a corresponding draw_dc_... primitive. The difference is that the draw_2d_... routines perform clipping to the rectangle specified in the rendition, while the draw_dc_...routines do not.

See Also HT_Physical_Renderer, HT_Device, HT_Drawing_Action Access Methods

Access methods are listed here with brief descriptions, under logical categories. Detailed descriptions with code synopses follow in alphabetical order.

Constructor/Destructor

HT_Renderer

Constructs an HT_Renderer object.

~HT_Renderer

Destroys an HT_Renderer object. Control Methods and Configuration

begin_picture

Signals to the driver the beginning of a sequence of drawing commands.

begin_picture_all

Signals to the driver the beginning of a sequence of drawing commands for each subsequent renderer in the stack.

configure

Queries a specific configured option value given a string.

configured_renderer_options

Returns the configured renderer option table.

current

Queries a specific current option value given a string.

current_child

Returns the current child renderer from the child renderer list.

current_renderer_options

Returns the current renderer option table.

data

Returns the HT_Renderer_Data class. This is rarely used by either the application or the driver.

device

Returns the device, that is, the sink of the renderer stack.

end_picture

Signals to the driver the end of a sequence of drawing commands.

end_picture_all

Signals to the driver the end of a sequence of drawing commands similar to end_picture, but for all preceding renderers in the stack.

establish

Reconciles the options of the current renderer with those of its sink.

establish_all

Reconciles configured options with current option table similar to establish but for all parents of the current device.

establish_configuration

Allows a driver to examine options set by the application and configure itself internally to honor those options. Returns zero when succeeded; nonzero otherwise.

first_child

Returns the first child renderer from the child renderer list.

get_module_info

Returns the HT_Module_Info associated with the renderer.

inherited_option_table

Returns the inherited configuration option table.

inherited_renderer_options

Returns the renderer options.

next_child

Returns the next child renderer from the child renderer list.

number_of_children

Returns the number of child renderers.

parent

Returns the sink renderer object of this renderer object.

query_user_configuration

Allows a driver to communicate with the user and returns the preferences to its caller.

set_configure

Sets a particular renderer configuration option.

update

Signals to the renderer the end of a display frame.

update_all

Signals to the renderer the end of a display frame but for all of the parents of the current device. 3D drawing methods

draw_3d_linestrip

Draws a series of lines with associated segment colors and vertex normals.

draw_3d_markerstrip

Draws a series of markers with associated marker colors and vertex normals.

draw_3d_polygon

Draws a filled polygon of constant color, optionally patterned.

draw_3d_polyline

Draws a polyline, possibly styled.

draw_3d_polymarker

Draws a series of markers with consistent color.

draw_3d_polytriangle

Draws a strip of triangles filled with a constant color, optionally patterned.

draw_3d_text

This action draws 3D text similar to other geometry, instead of directly calling the Font Engine.

draw_3d_tristrip

Draws a strip of triangles with associated face and vertex colors, vertex normals, edge colors, edge normals, and texture map parameters Frame and Depth Buffer Methods

clear_drawing_buffer

Clears the contents of the display buffer.

clear_z_buffer

Clears the contents of the depth buffer.

create_frame_buffer

Lets a renderer or driver supply a frame buffer to an application or another renderer.

display_frame_buffer

To display the contents of the frame buffer on the display.

draw_2d_image

Draws a generalized image accounting for the image format.

draw_dc_depth16_image

Fills a block of a 16-bit depth buffer with a depth image.

draw_dc_depth32_image

Fills a block of a 32-bit depth buffer with a depth image.

draw_dc_image

Draws a generalized image accounting for the image format.

draw_dc_index8_image

Draws a eight-bit indexed color image.

draw_dc_rgb32_image

Draws a 32-bit true color raster that is a consecutive set of 32-bit true-color raster lines.

read_dc_color_image

Reads back color data from the frame buffer to a memory block

read_dc_depth_image

Reads depth data from the Z buffer to a memory block.

draw_dc_bitonal_image

Draws a black and white image. 2D and DC drawing methods

draw_2d_dot, draw_dc_dot

Draws a dot.

draw_2d_ellipse, draw_dc_ellipse

Draws an ellipse or elliptical area.

draw_2d_elliptical_arc, draw_dc_elliptical_arc

Draws an elliptical arc segment.

draw_2d_gouraud_polyline,  draw_dc_gouraud_polyline

Draws a Gouraud shaded polyline.

draw_2d_gouraud_polytriangle, draw_dc_gouraud_polytriangle

Draws a Gouraud shaded triangle strip.

draw_2d_polygon, draw_dc_polygon

Draws a filled polygon of constant color, optionally patterned.

draw_2d_polyline, draw_dc_polyline

Draws a polyline, possibly styled.

draw_2d_polymarker, draw_dc_polymarker

Draws a series of markers with consistent color.

draw_2d_polytriangle, draw_dc_polytriangle

Draws a strip of triangles filled with a constant color, optionally patterned.

draw_2d_text

This action draws 2D text similar to other geometry, instead of directly calling the Font Engine.

draw_2d_textured_polyline, draw_dc_textured_polyline

Draws a polyline filled with a texture map.

draw_2d_textured_polymarker, draw_dc_textured_polymarker

Draws a polymarker filled with a texture map.

draw_2d_textured_polytriangle, draw_dc_textured_polytriangle

Draws a strip of triangles filled with a texture map. 2D and DC Drawing Methods with a list of specified colors

draw_2d_colorized_polyline, draw_dc_colorized_polyline

Draws a polyline, possibly styled.

draw_2d_colorized_polymarker, draw_dc_colorized_polymarker

Draws a series of markers with consistent color.

draw_2d_colorized_polytriangle, draw_dc_colorized_polytriangle

Draws a strip of triangles filled with a constant color, optionally patterned. Pattern Access Methods

face_pattern_bits

Returns the definition array for standard face pattern styles supported by Heidi.

line_pattern_lengths

Returns the definition array for standard line styles supported by Heidi. Operators

Operator ==

Compares renderer data

Operator !=

Compares the data of two renderers to see if they are equal.

Operator =

Assigns render data. Member Functions

HT_Renderer::begin_picture

Purpose

Signals to the driver the beginning of a sequence of drawing commands. Synopsis

void begin_picture ()

void begin_picture (HT_Document_Info * in = null) alter

Details This pure virtual function must be provided by each driver.

This method is a message from the application to the driver that a sequence of drawing commands is about to begin.

The second form is an optional pointer to class HT_Document_Info which enables the driver to distinguish between individual pages within a document, for hardcopy output.

See Also

begin_picture_all , update, end_picture

HT_Renderer::begin_picture_all

Purpose

Signals to the driver the beginning of a sequence of drawing commands for each subsequent renderer in the stack. Synopsis

void begin_picture_all ()

void begin_picture_all (HT_Document_Info * in = null) alter

Details The pure virtual function begin_picturemust be provided by each driver to signal the beginning of a sequence of drawing commands. begin_picture_all is a convenient function which proceeds down the renderer stack starting from the current renderer and declares a begin_picture for the current and each subsequent renderer.

The second form is an optional pointer to class HT_Document_Info which enables the driver to distinguish between individual pages within a document, for hardcopy output.

HT_Renderer::clear_drawing_buffer

Purpose

Clear the contents of the display buffer. Synopsis

void clear_drawing_buffer (
    HT_Rendition const & hr
)

Details The contents of the display buffer should be cleared with the background color in the rendition.

HT_Renderer::clear_z_buffer

Purpose

Clear the contents of the depth buffer. Synopsis

void clear_z_buffer (
    HT_Rendition const & hr
)

Details

HT_Renderer::configure

Purpose

Queries a specific configured option value given a string. Synopsis

HT_Option_Value configure (
    HT_String const & name
)

Details Options are stored in (name, value) pairs. This routine returns the current option value for a given option name. The option may be set using member functions of the HT_Option_Value class. The new value is then set using the set_configure() method. After modifying all necessary options, the application reconciles them to the driver by calling establish() which calls the function establish_configuration() and must be supplied by each driver.

You can set a particular option name on a particular renderer *rend using three or more function calls. For example,

    rend->set_configure("Window Origin", HT_Option_Value (x, y));

sets the "Window Origin" option to (x,y). In this case, the option value is an array of two ints. For more details about option value, see class HT_Option_Value.

HT_Renderer::configured_renderer_options

Purpose

Returns the configured renderer option table. Synopsis

HT_Renderer_Options const & configured_renderer_options() const

Details

HT_Renderer::create_frame_buffer

Purpose

Lets a renderer or driver supply a software frame buffer to an application. Synopsis

void create_frame_buffer (int width, int height,

        HT_Image_Format const & format,

        HT_Shared_Image alter & buffer) const {

    m_data->create_frame_buffer (width, height, format, buffer);

Details This method is called to obtain image storage to serve as a software frame buffer.

If you provide this action, you have to allocate an HT_Shared_Image structure appropriate to the format, height, and width, and return its address in *buffer. Note also that HT_Image_Format now takes a reference or pointer according to the situation.

HT_Renderer::current

Purpose

Queries value of a renderer’s particular option. Synopsis

HT_Option_Value current (
    HT_String const & name
)

Details Options are stored in (name, value) pairs. This routine returns the current option value for a given option name from the current option table

HT_Renderer::current_child

Purpose

Returns the current child renderer from the child renderer list. Synopsis

HT_Renderer             current_child (HT_Position pos) const

Details A renderer maintains a list of its child renderers. Given the position pointer, this routine returns the current child renderer from the list.

HT_Renderer::current_renderer_options

Purpose

Returns the current renderer options. Synopsis

HT_Renderer_Options const & current_renderer_options() const

Details The current renderer option class is returned. This can be used by a driver at establish_configuration time to query the application’s settings of the renderer options.

For further details on renderer options, see the "Driver Options" section of chapter 2, "Heidi Architecture." For more information on driver implementation, see the "Driver Linkage" section of chapter 3, "Implementing a New Driver."

HT_Renderer::data

Purpose

Returns the data class associated with this renderer object. Synopsis

HT_Renderer_Data const & data (void) const

Details This is a rarely used internal data class. Applications as well as drivers should always access the information with HT_Renderer instead of the data class.

HT_Renderer::device

Purpose

Returns the device object associated with this renderer object. Synopsis

HT_Device const * device ()

Details The device is the renderer at the root of the renderer tree containing this renderer object.

HT_Renderer::display_frame_buffer

Purpose

To display the contents of the frame buffer on the hardware display. Synopsis

void display_frame_buffer (HT_DC_Point const * start,
                           HT_DC_Point const * end,
                           HT_Shared_Image const * buffer,
                           int hoffset, int voffset) const

Details Called at the end of a software frame buffer update cycle to cause the driver to display on the device the image rendered to the software frame buffer.

start and end tell, in device coordinates, where to display the image.

*buffer contains the image to be displayed

hoffset and voffset specify possible offsets within the image.

HT_Renderer::draw_2d_colorized_polyline
HT_Renderer::draw_dc_colorized_polyline

Purpose

Draws a polyline, specified in device coordinates, with color specified by the argument colors. Synopsis

void draw_2d_colorized_polyline (
    HT_Rendition const & hr,
    int count,



    HT_DC_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const
void draw_dc_colorized_polyline (
    HT_Rendition const & hr,
    int count,
    HT_DC_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const 
void draw_2d_colorized_polyline (
    HT_Rendition const & hr,
    int count,
    HT_DCI_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const 
void draw_dc_colorized_polyline (
    HT_Rendition const & hr,
    int count,
    HT_DCI_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const

Details This is similar to draw_2d/dc_polyline except that the color is given by the argument instead of any attribute in the rendition. single_color is a boolean indicating if there is more than one color in colors.

HT_Renderer::draw_2d_colorized_polymarker
HT_Renderer::draw_dc_colorized_polymarker

Purpose

Draws a polymarker, specified in device coordinates, with color specified by the argument colors. Synopsis

void draw_2d_colorized_polymarker (
    HT_Rendition const & hr,
    int count,
    HT_DC_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const 
void draw_dc_colorized_polymarker (
    HT_Rendition const & hr,
    int count,
    HT_DC_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const 
void draw_2d_colorized_polymarker (
    HT_Rendition const & hr,
    int count,
    HT_DCI_Point const *points, 
    HT_RGB32 const *colors,
    HT_Boolean single_color) const 
void draw_dc_colorized_polymarker (
    HT_Rendition const & hr,
    int count,
    HT_DCI_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const

Details This is similar to draw_2d/dc_polymarkerexcept that the color is given by the argument instead of any attribute in the rendition. single_color is a boolean indicating if there is more than one color incolors.

HT_Renderer::draw_2d_colorized_polytriangle
HT_Renderer::draw_dc_colorized_polytriangle

Purpose

Draws a polytriangle, specified in device coordinates, with color specified by the argument colors. Synopsis

void draw_2d_colorized_polytriangle (
    HT_Rendition const & hr,
    int count,
    HT_DC_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const 
void draw_dc_colorized_polytriangle (
    HT_Rendition const & hr,
    int count,
    HT_DC_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const 
void draw_2d_colorized_polytriangle (
    HT_Rendition const & hr,
    int count,
    HT_DCI_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const 
void draw_dc_colorized_polytriangle (
    HT_Rendition const & hr,
    int count,
    HT_DCI_Point const *points,
    HT_RGB32 const *colors,
    HT_Boolean single_color) const

Details This is similar to draw_2d/dc_polytriangle except that the color is given by the argument instead of any attribute in the rendition. single_color is a boolean indicating if there is more than one color in colors.

HT_Renderer::draw_2d_dot
HT_Renderer::draw_dc_dot

Purpose

Draws a dot at the specified device coordinate location. Synopsis

void draw_2d_dot (
    HT_Rendition const & hr,
    HT_DC_Point const & point,
    HT_RGB32 * color = null) const 
void draw_dc_dot (
    HT_Rendition const & hr,
    HT_DC_Point const & point,
    HT_RGB32 * color = null) const 
void draw_2d_dot (
    HT_Rendition const & hr,
    HT_DCI_Point const & point,
    HT_RGB32 * color = null) const 
void draw_dc_dot (
    HT_Rendition const & hr,
    HT_DCI_Point const & point,
    HT_RGB32 * color = null) const

Details This routine draws a smallest visible dot, typically a single pixel. point gives the location. color specifies the drawing color when it is not null; otherwise the rendition color is used.

HT_Renderer::draw_2d_ellipse
HT_Renderer::draw_dc_ellipse

Purpose

Draws a filled ellipse or "pie shaped" elliptical area, specified in device coordinates. Synopsis

    void draw_2d_ellipse (HT_Rendition const & hr,
                          HT_DC_Point const & center,
                          HT_DC_Point const & radii,
                          float start = 0.0f,
                          float end = HK_Two_Pi,
                          float tilt = 0.0f,
                          HT_RGB32 * color = null) const {
            read().draw_2d_ellipse (hr, center, radii, start, end, tilt, color);
    }
    void draw_dc_ellipse (HT_Rendition const & hr,
                          HT_DC_Point const & center,
                          HT_DC_Point const & radii,
                          float start = 0.0f,
                          float end = HK_Two_Pi,
                          float tilt = 0.0f,
                          HT_RGB32 * color = null) const {
            read().draw_dc_ellipse (hr, center, radii, start, end, tilt, color);
    }
    void draw_2d_ellipse (HT_Rendition const & hr,
                          HT_DCI_Point const & center,
                          HT_DCI_Point const & radii,
                          float start = 0.0f,
                          float end = HK_Two_Pi,
                          float tilt = 0.0f,
                          HT_RGB32 * color = null) const {
            read().draw_2d_ellipse (hr, center, radii, start, end, tilt, color);
    }
    void draw_dc_ellipse (HT_Rendition const & hr,
                          HT_DCI_Point const & center,
                          HT_DCI_Point const & radii,
                          float start = 0.0f,
                          float end = HK_Two_Pi,
                          float tilt = 0.0f,
                          HT_RGB32 * color = null) const {
            read().draw_dc_ellipse (hr, center, radii, start, end, tilt, color);
     }

Details This routine draws a filled elliptical area, or "pie wedge", aligned with the device coordinate axes.

center is the position of the center of the ellipse. radii.x and radii.y give the semi-axes, in device coordinate units. start and end give the starting and ending angles for the elliptical section or "pie wedge", in radians. For more information on parameterization of start and end angles see draw_2d_elliptical_arc. If tilt is specified, the ellipse is rotated about its center point.

An example of the ellipse parameters for a filled ellipse are shown in figure 1.

Figure 1. Ellipse parameters—filled ellipse

If your device is good at drawing solidly filled ellipses, but not pattern-filled ellipses, then you can punt to the standard drawing function HD_Standard_Draw_2D/DC_Ellipse. color specifies the drawing color when it is not null; otherwise the rendition color is used. The second form is for DCI.

Note: For a continuation of class HT_Renderer, go to the draw_2d_elliptical_arcmethod.