TkGS Specification - Drawables

Introduction

TkGS uses a state-based model. Graphics operations are performed on a TkGS_Drawable, which can refer to any device: native window, Tk-emulated Xlib window, PostScript generator... A TkGS_Drawable must be obtained before any graphics operation and must be released at the end.

TkGS_Drawables are device-independent: they use object-oriented paradigms, can be obtained from real-world objects (windows, printers...) or be user-defined through the use of device drivers (eg. PostScript, OpenGL...). Also, each TkGS_Drawable exposes its capabilities in a device-independent manner.

Conceptually speaking, a TkGS_Drawable is very close to a Windows DC (Device Context), in the sense that it is attached to a specific device (eg. a window) and holds a drawing state, or context (eg. drawing colors). Despite its name, it is quite different from a X Drawable. In the special case of X, a TkGS_Drawable should contain information about the display, the drawable (window or pixmap), and the GC. As X is rather stateless, all three are usually passed to drawing primitives. Under TkGS, only the TkGS_Drawable is needed. Internally, TkGS_Drawables are implemented using TkGS_Objs. As seen from the outside, TkGS_Drawables are opaque tokens.

Structures


TkGS_Drawable
Description
A TkGS_Drawable corresponds to the drawing area on which primitives are called. it retains state information about parameters such as color, font, etc. (see TkGS_GC).
This document does not specify how TkGS_Drawables are obtained (however it provides an interface to get a TkGS_Drawable from a Tk_Window). Extension writers may provide their own APIs for returning valid TkGS_Drawables. For example, a PostScript driver may provide an API for getting a TkGS_Drawable to generate a PostScript page of a given size. A native Windows printer extension may provide an API for opening a printer dialog that returns a TkGS_Drawable corresponding to a given print job. The goal of TkGS is only to provide a device-independent way of performing graphics jobs.
Structure
TkGS_Drawable is an opaque token that holds system-independent drawable information. Its internals could for example hold X or Window-specific data about the drawable (window, printer context...).
TkGS_Drawable's internals are defined by the TkGS_Drawable_< /A> structure (notice the trailing underscore).

Functions


TkGS_GetDrawableDevice
Description
Retrieve the TkGS_Device associated with the given TkGS_Drawable.
Status
Specification complete. Currently implemented as a macro.
Declaration
TkGS_Device TkGS_GetDevice(
    TkGS_Drawable drawable
);
Arguments
drawable: the TkGS_Drawable we want to get information about.
Returned value
The corresponding TkGS_Device.
Side effects
None.

TkGS_ReleaseDrawable
Description
This function is used to release a TkGS_Drawable previously returned by device-specific procedures, once the drawing is complete. While obtaining a valid TkGS_Drawable depends on the device (window, printer, pixmap...), releasing it is done in a device-independent manner.
Declaration
void TkGS_ReleaseDrawable(
    TkGS_Drawable drawable
);
Arguments
drawable: the TkGS_Drawable to release.
Returned value
None.
Side effects
Storage is freed, drawable is not valid anymore.

TODO