Devices in the graphcis state Chaining devices Subclassing Example uses Observations Worked example
The 'device' is a member of the graphics state in PostScript, and is subject to gsave/grestore, like any other part of the graphics state. This is important for PostScript as it allows us to, for example, push the null device, perform some operations, and then grestore back to the original rendering device.
In PostScript and PDF, the graphics state is itself a garbage collected object, as is the device. This means that we store a pointer to the device in the graphics state, which forces the other interpreters to do so as well. Now an important implication of this is that it is then only possible, currently, to change devices by altering the graphics state entry to point at a different device structure, which means that the graphics state must be available in order to do so. Clearly at the interpreter level this isn't a problem, but at lower levels the graphics state may not be available, not all our device methods pass on a graphics state pointer for example. Without that pointer we can't change the graphics state and therefore can't point at a different device.
There are times when it is useful to be able to chain devices one after another, examples include the PDF transparency device, the pattern accumulator device and others. Some comments in early code indicate that the ability to chain devices was an original design goal, though its likely that originally this was only intended to work by installing devices from the interpreter level.
Currently there are a number of different ways to install devices, and the sheer number, and the methods themselves, show why there is a problem. Lets consider them separately.
Taken together we have a number of different routes to install devices, but none of them is totally satisfactory for the goal of creating a chain of devices without access to the graphics state. However I think the existence of these manifold routes do indicate that there has been a recognition in the past that this would be useful to have.
From the above, its clear that we need to use some approach similar to the clist and spy devices. We must retain the original device memory, because that is what the graphics state points to, which means that we must reuse that memory in some fashion. By making a copy of the existing device elsewhere, we can then recycle the existing device.
As a short summary, that's precisely what the device subclassing code does. It examines the existing device, makes a new device structure sufficiently large to take a copy of it, and copies the existing device and all its state to that new memory. It then uses the prototype supplied for the new class, and writes that into the original device memory.
In order to chain the devices together, I've added three new pointers to the device structure (so that all devices can be chained), a child, a parent and a 'data' pointer (see below). Whenever we subclass a device the copied device gets its parent member set to the original device pointer, and the new device points to the copied one using the child member.
Now a subtle point here is that, because we cannot change the size of the memory allocated for the original device (as that might relocate it, invalidating the graphics state pointer) its absolutely vital that the new device must be no larger than the old device. This means we have to be careful about data which the new device needs, we can't simply store it in the device structure as we usually do. To resolve that I've also added a void pointer to hold private data, the new device should allocate as much data as it requires (eg a structure) and store a pointer to that data in the subclass_data pointer. I'd recommend that this is allocated from non-GC memory except in special cases. This should mean that subclassing devices are never larger than a gx_device structure and so never overflow.
In order to minimise the number of methods that a subclassing device needs to define I've created 'default' methods for all the possible device methods. Subclassing devices should use these in their prototype for any methods they don't handle. Additionally these can be used to pass on any methods after processing by the subclassing device, if required.
The original justification for this work was to create a device which would add 'first page' and 'last page' functionality to all the languages and all the devices. The gdevflp.c file incorporates exactly that, it has been added to gdevprn.c and gdevvec.c so that any device based on either of these two basic devices will simply work. Additionally other devices which are not based on either of these (eg the 'bit' device) have been appropriately modified.
If -dFirstPage or -dLastPage is set the parameter is parsed out and the existing device is
subclassed by the new First/Last page device. This device simply drops all marking operations, and 'output_page' operations
until we reach the page defined by FirstPage, and then passes everything through to the real device until we pass the page
defined by LastPage at which point it throws everything away again until the end of the input.
Now, this is not as efficient as the PDF interpreter's usage, which only passes those pages required to be rendered. So the
old functionality has been preserved in the PDF interpreter, exactly as before. In order to prevent the subclassing device
addionally acting on the same parameters, there is a DisablePageHandler flag which is set by the PDF interpreter.
In order to test the chaining of devices together, I also created an 'object filtering' device; as with the first/last page
device this has been added to all devices and any device based off gdevprn or gdevvec should inherit the functionality
directly. This device allows objects to be dropped based on their type (text, image or linework) using the parameters
-dFILTERTEXT -dFILTERIMAGE and -dFILTERVECTOR, if a parameter is set then objects of that type
will not be rendered.
Finally the PCL interpreter now uses a subclassing device to implement the 'monochrome palette' rendering. Previously this directly modified the color_procs in the current device, which I suspect was prone to potential failure (for example if a forwarding device had been pushed). This eliminated a somewhat ugly hack (in fairness its not obvious what would have been better), as well as allowing me to do away with some global variables in the PCL interpreter.
The monochrome palette device illuminated an interesting problem in the graphics library. Normally the device calls the graphics library for rendering services, but the color_procs work in reverse, the graphics library calls the device directly in order to map the colours. In the case of chained devices this meant that only the final device was being called. This was unacceptable in a situation involving chained devices, it seemed obvious to me that the graphics library should pass the request to the head of the device chain for processing. There is no simple way to do this (no access to the graphics state!) so instead I used the linked list of child/parent pointers to walk up to the head of the list, and then submit the request to that device.
The ICC profile code has a 'get_profile' method in the device API to retrieve a profile, but it has no corresponding 'set_profile' method, it simply sets the structure member in the current device. This caused some serious problems. Consider the case where the ICC code executes a get_profile and no profile is yet set (returning NULL). The code would then create a profile and attach it directly to the current device. It then executes 'get_profile' again. If the current device was a subclassing device, or a forwarding device, then the 'set' would have set the profile in that device, but the 'get' would retrieve it from the underlying device, which would still be NULL. Since the ICC code didn't test the result on the second call this caused a segmentation fault. I've modified the ICC code to set the profile in the lowest device, but this probably ought to be improved to define a new 'set_profile' method.
The tag devices write an extra colour plane in the output, where the value of the sample encodes the type of graphic that was rendered at that point (text, image, path, untouched or unknown). This is done by encoding the type in the color, which is performed by the graphics library. Now, when the type of operation changes (eg from image to text) we need to tell the graphics library that there has been a change. We do this by calling the set_graphics_type_tag device method. However, when encoding a color, the graphics library does not, as one might expect call a matching get_graphics_type method, instead it directly inspects the devcie structure and reads the graphics_type_tag member. This means that all devices in the chain must maintain this member, the implication is that if a subclassing device should implement its own set_graphics_type_tag method, it must update the graphics_type_tag in its device structure appropriately, and pass the method on to the next device in the chain. The default method already does this.
Its pretty clear from reading through the code that the original intention of the device methods is that all methods in a device should be filled in, they should never be NULL (exception; fill_rectangle is deliberately excluded from this) if a device does not implement a method then 'fill_in_procs' should set a default method (which may legitimately simply throw an error). Over time this decision has not been enforced with the result that we now have some places where methods may be NULL. This has meant that there are places in the code which have to check for a method being NULL before using it, which is (I think) exactly what we were originally trying to avoid. Worse, since there is no list of which methods may be NULL a sensible developer would have to test all methods before use. Worst of all, it looks like some places may take a NULL method as having specific meaning (gsdparam.c line 272). We should really tidy this up.
General observations are recorded in comments in gdevsclass.c
To see how to use the device subclassing we'll take a concrete example and implement it in a real device. For the purposes of the example we'll do a 'force black text' device and add it to the TIFF device(s). The reason for choosing the TIFF devices is that these already have an 'open_device' method which we are going to use to install the subclassing device. This isn't essential, you could install the device at any point, but its convenient.
The first thing we need to do is add some control to turn this feature off and on, this is normally done by setting device
parameters on the command line. To implement this we will need to modify the put_params and get_params methods. Note it is
important to add new parameters to both the get and put methods, or an error will occur. We'll call our new parameter
ForceBlackText.
First we add the new parameter to the TIFF device, defined in gdevtifs.h:
typedef struct gx_device_tiff_s {
gx_device_common;
gx_prn_device_common;
bool ForceBlackText;
bool BlackTextHandlerPushed;
....
}
Note that we also have a boolean value 'BlackTextHandlerPushed' to track whether the device is already pushed or not, we'll want to use this later.
We also need to add default values to the device prototypes, which are defined in gdevtfnx.c:
const gx_device_tiff gs_tiff12nc_device = {
prn_device_std_body(gx_device_tiff, tiff12_procs, "tiff12nc",
DEFAULT_WIDTH_10THS, DEFAULT_HEIGHT_10THS,
X_DPI, Y_DPI,
0, 0, 0, 0,
24, tiff12_print_page),
0, /* ForceBlacktext */
0, /* BlacktextHandlerPushed */
arch_is_big_endian /* default to native endian (i.e. use big endian iff the platform is so*/,
Repeat for gs_tiff24nc_device and gs_tiff48nc_device. For unknown reasons, the remaining TIFF devices are in gdevtsep.c, we need to make the same changes to the prototypes there; gs_tiffgray_device gs_tiffscaled_device gs_tiffscaled8_device gs_tiffscaled24_device gs_tiffscaled32_device gs_tiffscaled4_device gs_tiff32nc_device gs_tiff64nc_device and finally tiffsep_devices_body.
Now we add code to put_params and get_params to set the parameter, and report its value back to the interpreter. In gdevtifs.c:
static int
tiff_get_some_params(gx_device * dev, gs_param_list * plist, int which)
{
gx_device_tiff *const tfdev = (gx_device_tiff *)dev;
int code = gdev_prn_get_params(dev, plist);
int ecode = code;
gs_param_string comprstr;
if ((code = param_write_bool(plist, "ForceBlackText", &tfdev->ForceBlackText)) < 0)
ecode = code;
....
}
static int
tiff_put_some_params(gx_device * dev, gs_param_list * plist, int which)
{
gx_device_tiff *const tfdev = (gx_device_tiff *)dev;
int ecode = 0;
int code;
const char *param_name;
bool big_endian = tfdev->BigEndian;
bool usebigtiff = tfdev->UseBigTIFF;
uint16 compr = tfdev->Compression;
gs_param_string comprstr;
long downscale = tfdev->DownScaleFactor;
long mss = tfdev->MaxStripSize;
long aw = tfdev->AdjustWidth;
long mfs = tfdev->MinFeatureSize;
bool ForceBlackText = tfdev->ForceBlackText;
/* Read ForceBlackText option as bool */
switch (code = param_read_bool(plist, (param_name = "ForceBlackText"), &ForceBlackText)) {
default:
ecode = code;
param_signal_error(plist, param_name, ecode);
case 0:
case 1:
break;
}
/* Read BigEndian option as bool */
switch (code = param_read_bool(plist, (param_name = "BigEndian"), &big_endian)) {
...
tfdev->MinFeatureSize = mfs;
tfdev->ForceBlackText = ForceBlackText;
return code;
}
Checking the TIFF device's open method (tiff_open) we see that it already potentially has two subclassing devices, this is because it doesn't inherit from gdev_prn, if it did this functionality would be inherited as well. We can just go ahead and add our new subclassing device in here.
int
tiff_open(gx_device *pdev)
{
gx_device_printer * const ppdev = (gx_device_printer *)pdev;
gx_device_tiff *tfdev = (gx_device_tiff *)pdev;
int code;
bool update_procs = false;
/* Use our own warning and error message handlers in libtiff */
tiff_set_handlers();
if (!tfdev->BlackTextHandlerPushed && (tfdev->ForceBlackText != 0)) {
gx_device *dev;
gx_device_subclass(pdev, (gx_device *)&gs_black_text_device, sizeof(black_text_subclass_data));
tfdev = (gx_device_tiff *)pdev->child;
tfdev->BlackTextHandlerPushed = true;
while(pdev->child)
pdev = pdev->child;
pdev->is_open = true;
update_procs = true;
}
You might notice that this is a little simpler than the other device installations, that's because the other devices can potentially be installed by any device, and we need to track them more carefully. Our new device can only be installed by the TIFF device, so we don't need to note that its been installed already, in all the parent and child devices. This is only done so that we don't accidentally install these more basic devices more than once.
So the first thing we do is check to see if we've already installed the device to force black text (we can potentially call the open method more than once and we don't want to install the device multiple times). If we haven't installed the device yet, and the feature has been requested, then we call the code to subclass the current device using the 'black_text_device' as the prototype for the new device, and pass in the amount of data it requires for its private usage.
We will be defining this device as the next steps, for now just notice that after we call this, the 'current' device in the graphics state will be the black_text_device, and its 'child' member will be pointing to the TIFF device. So we note in that child device that we have pushed the black text handling device. We also note that the TIFF device is 'open' (the calling code will do this for the device pointed to by the graphics state, ie the black text device). Finally we set a boolean to 'update procs'. This is needed because the tiff_open routine calls gdev_prn_allocate_memory which resets the device methods, we need to put them back to be correct for our device(s), which is done at the end of the tiff_open code:
if (update_procs) {
if (pdev->ObjectHandlerPushed) {
gx_copy_device_procs(&pdev->parent->procs, &pdev->procs, (gx_device_procs *)&gs_obj_filter_device.procs);
pdev = pdev->parent;
}
if (pdev->PageHandlerPushed) {
gx_copy_device_procs(&pdev->parent->procs, &pdev->procs, (gx_device_procs *)&gs_flp_device.procs);
pdev = pdev->parent;
}
/* set tfdev to the bottom device in the chain */
tfdev = (gx_device_tiff *)pdev;
while (tfdev->child)
tfdev = (gx_device_tiff *)tfdev->child;
if (tfdev->BlackTextHandlerPushed)
gx_copy_device_procs(&pdev->parent->procs, &pdev->procs, (gx_device_procs *)&gs_black_text_device.procs);
}
In essence this simply works backwards through the chain of devices, restoring the correct methods as it goes. Note that because the BlackTextHandlerPushed variable isn't defined in the basic device structure, we have to cast the device pointer to a gx_device_tiff * so that we can set and check the variable which is defined there.
That completes the changes we need to make to the TIFF device to add support for our new code. Now we need to create the black_text device which will do the actual work.
We don't need any extras in the device structure, so we'll just define our subclassing device as being a gx_device:
/* Black Text device */
typedef struct gx_device_s gx_device_black_text;
We also don't need any extra storage, but we do need to carry round the basic storage required by a subclassing device, so we do need to define a structure for that:
typedef struct {
subclass_common;
} black_text_subclass_data;
Now, we are going to deal with text (obviously) and text, like images, is handled rather awkwardly in the current device interface. Instead of the interpreter calling the various device methods, the 'text_begin' method creates a text enumerator which it returns to the interpreter. The text enumerator contains its own set of methods for dealing with text, and the interpreter calls these, thus bypassing the device itself. Since our subclassing requires us to pass down a chain of devices, when dealing with text and images we must also implement a chain of enumerators. For subclassing devices which don't process text or images this is catered for in the default_subclass_* methods, but in this case we need to handle the situation.
We start by creating our own text enumerator structure:
typedef struct black_text_text_enum_s {
gs_text_enum_common;
gs_text_enum_t *child;
} black_text_text_enum_t;
Here we have a structure which contains the elements common to all enumerators, and a pointer to the next enumerator in the chain, we'll fill that in later.
Ghostscript uses several memory managers, but for PostScript and PDF objects we use a garbage collector. Because we may want to store pointers to garbage collected objects in the text enumerator, and our device, we need to make the garbage collector aware of them. This is because the garbage collector can relocate objects in memory, in order to do so safely it needs to update any pointers referencing those objects with the new location and so it needs to be told about those pointers.
So, we define a garbage collector structure for the text enumerator:
extern_st(st_gs_text_enum);
gs_private_st_suffix_add1(st_black_text_text_enum, black_text_text_enum_t,
"black_text_text_enum_t", black_text_text_enum_enum_ptrs, black_text_text_enum_reloc_ptrs,
st_gs_text_enum, child);
The macro 'extern_st' simply defines the structure (st_gs_text_enum) as being of type gs_memory_struct_type_t. We need this structure for the 'superstructure' defined below.
The next macro 'gs_private_st_suffix_add1' is one of a family of macros used to define structures for the garbage collector. These all end up defining the named structure as being of type 'gc_struct_data_t' and fill in various members of that structure. In this case we are declaring that the structure:
So now we have to do a similar job for the actual device itself. We start by defining the enumeration and relocation routines for the structure. There are extensive macros for doing this, and we make use of some of them here. Explaining these is out of the scope of this document, but they are defined and easy to locate in the Ghostscript source tree.
static
ENUM_PTRS_WITH(black_text_enum_ptrs, gx_device *dev);
return 0; /* default case */
case 0:ENUM_RETURN(gx_device_enum_ptr(dev->parent));
case 1:ENUM_RETURN(gx_device_enum_ptr(dev->child));
ENUM_PTRS_END
static RELOC_PTRS_WITH(black_text_reloc_ptrs, gx_device *dev)
{
dev->parent = gx_device_reloc_ptr(dev->parent, gcst);
dev->child = gx_device_reloc_ptr(dev->child, gcst);
}RELOC_PTRS_END
Essentially these simply tell the garbage collector that we are maintaining two pointers to garbage collected objects, the parent and child devices. Now we use those in the garbage collector 'structure descriptor' for the device. Note this is not the actual device structure, its the structure used by the garbage collector when dealing with the device.
gs_public_st_complex_only(st_black_text_device, gx_device, "black_text",
0, black_text_enum_ptrs, black_text_reloc_ptrs, gx_device_finalize);
Again 'gs_public_st_complex_only' is a macro, and its one of a family, these end up defining structures of type 'gs_memory_struct_t'. In this case we are declaring:
/* Device procedures */
static dev_proc_text_begin(black_text_text_begin);
Then we define the actual device:
const
gx_device_black_text gs_black_text_device =
{
std_device_dci_type_body(gx_device_black_text, 0, "black_text", &st_black_text_device,
MAX_COORD, MAX_COORD,
MAX_RESOLUTION, MAX_RESOLUTION,
1, 8, 255, 0, 256, 1),
{default_subclass_open_device,
default_subclass_get_initial_matrix,
default_subclass_sync_output, /* sync_output */
default_subclass_output_page,
default_subclass_close_device,
default_subclass_map_rgb_color,
default_subclass_map_color_rgb,
default_subclass_fill_rectangle,
default_subclass_tile_rectangle, /* tile_rectangle */
default_subclass_copy_mono,
default_subclass_copy_color,
default_subclass_draw_line, /* draw_line */
default_subclass_get_bits, /* get_bits */
default_subclass_get_params,
default_subclass_put_params,
default_subclass_map_cmyk_color,
default_subclass_get_xfont_procs, /* get_xfont_procs */
default_subclass_get_xfont_device, /* get_xfont_device */
default_subclass_map_rgb_alpha_color,
default_subclass_get_page_device,
default_subclass_get_alpha_bits, /* get_alpha_bits */
default_subclass_copy_alpha,
default_subclass_get_band, /* get_band */
default_subclass_copy_rop, /* copy_rop */
default_subclass_fill_path,
default_subclass_stroke_path,
default_subclass_fill_mask,
default_subclass_fill_trapezoid,
default_subclass_fill_parallelogram,
default_subclass_fill_triangle,
default_subclass_draw_thin_line,
default_subclass_begin_image,
default_subclass_image_data, /* image_data */
default_subclass_end_image, /* end_image */
default_subclass_strip_tile_rectangle,
default_subclass_strip_copy_rop,
default_subclass_get_clipping_box, /* get_clipping_box */
default_subclass_begin_typed_image,
default_subclass_get_bits_rectangle, /* get_bits_rectangle */
default_subclass_map_color_rgb_alpha,
default_subclass_create_compositor,
default_subclass_get_hardware_params, /* get_hardware_params */
black_text_text_begin,
default_subclass_finish_copydevice, /* finish_copydevice */
default_subclass_begin_transparency_group, /* begin_transparency_group */
default_subclass_end_transparency_group, /* end_transparency_group */
default_subclass_begin_transparency_mask, /* begin_transparency_mask */
default_subclass_end_transparency_mask, /* end_transparency_mask */
default_subclass_discard_transparency_layer, /* discard_transparency_layer */
default_subclass_get_color_mapping_procs, /* get_color_mapping_procs */
default_subclass_get_color_comp_index, /* get_color_comp_index */
default_subclass_encode_color, /* encode_color */
default_subclass_decode_color, /* decode_color */
default_subclass_pattern_manage, /* pattern_manage */
default_subclass_fill_rectangle_hl_color, /* fill_rectangle_hl_color */
default_subclass_include_color_space, /* include_color_space */
default_subclass_fill_linear_color_scanline, /* fill_linear_color_scanline */
default_subclass_fill_linear_color_trapezoid, /* fill_linear_color_trapezoid */
default_subclass_fill_linear_color_triangle, /* fill_linear_color_triangle */
default_subclass_update_spot_equivalent_colors, /* update_spot_equivalent_colors */
default_subclass_ret_devn_params, /* ret_devn_params */
default_subclass_fillpage, /* fillpage */
default_subclass_push_transparency_state, /* push_transparency_state */
default_subclass_pop_transparency_state, /* pop_transparency_state */
default_subclass_put_image, /* put_image */
default_subclass_dev_spec_op, /* dev_spec_op */
default_subclass_copy_planes, /* copy_planes */
default_subclass_get_profile, /* get_profile */
default_subclass_set_graphics_type_tag, /* set_graphics_type_tag */
default_subclass_strip_copy_rop2,
default_subclass_strip_tile_rect_devn,
default_subclass_copy_alpha_hl_color,
default_subclass_process_page
}
};
Much of this is simply boilerplate, defining the device methods as being the default methods for a subclassing device. The exception being the text_begin method. The main body of the macro is:
const
gx_device_black_text gs_black_text_device =
{
std_device_dci_type_body(gx_device_black_text, 0, "black_text", &st_black_text_device,
MAX_COORD, MAX_COORD,
MAX_RESOLUTION, MAX_RESOLUTION,
1, 8, 255, 0, 256, 1),
This simply defines an instance of the 'gx_device_black_text' structure (which is simply a gx_device_s structure) initialised using a macro (yet another family of macros). Here we use the 'st_black_text_device' structure descriptor we created above, and some dummy values for the resolution, colour depth etc. Since this device doesn't do rendering these values aren't useful and these defaults should be fine.
Now, for text we need to fill in all the procedures in the text enumerator, we'll start by defining the 'resync' method, and then use this as a template for most of the other methods in the text enumerator:
static int
black_text_text_resync(gs_text_enum_t *pte, const gs_text_enum_t *pfrom)
{
black_text_text_enum_t *penum;
gs_text_enum_t * child = penum->child;
int code;
code = child->procs->resync(child, pfrom);
gs_text_enum_copy_dynamic(pte, child, true);
return code;
}
The routine starts by casting the generic text enumerator to our specific type of text enumerator. From that we can get the child enumerator, and we simply pass the operation on directly to the child (remembering to pass the child enumerator as an argument, not our own one!).
Now, on return it may be that the child has modified the contents of the enumerator, so we must copy anything that might have changed from the child enumerator to our own. That's what the 'gs_text_enum_copy_dynamic' routine does. After that we simply return the saved return value.
All the other routines are basically the same as this, we don't really want to do anything in the text enumeration so we just hand off the processing to the child.
static int
black_text_text_process(gs_text_enum_t *pte)
{
black_text_text_enum_t *penum = (black_text_text_enum_t *)pte;
gs_text_enum_t * child = penum->child;
int code;
code = child->procs->process(child);
gs_text_enum_copy_dynamic(pte, child, true);
return code;
}
static bool
black_text_text_is_width_only(const gs_text_enum_t *pte)
{
black_text_text_enum_t *penum = (black_text_text_enum_t *)pte;
gs_text_enum_t * child = penum->child;
int code;
code = child->procs->is_width_only(child);
gs_text_enum_copy_dynamic((gs_text_enum_t *)pte, child, true);
return code;
}
static int
black_text_text_current_width(const gs_text_enum_t *pte, gs_point *pwidth)
{
black_text_text_enum_t *penum = (black_text_text_enum_t *)pte;
gs_text_enum_t * child = penum->child;
int code;
code = child->procs->current_width(child, pwidth);
gs_text_enum_copy_dynamic((gs_text_enum_t *)pte, child, true);
return code;
}
static int
black_text_text_set_cache(gs_text_enum_t *pte, const double *pw,
gs_text_cache_control_t control)
{
black_text_text_enum_t *penum = (black_text_text_enum_t *)pte;
gs_text_enum_t * child = penum->child;
int code;
code = child->procs->set_cache(child, pw, control);
gs_text_enum_copy_dynamic(pte, child, true);
return code;
}
static int
black_text_text_retry(gs_text_enum_t *pte)
{
black_text_text_enum_t *penum = (black_text_text_enum_t *)pte;
gs_text_enum_t * child = penum->child;
int code;
code = child->procs->retry(child);
gs_text_enum_copy_dynamic(pte, child, true);
return code;
}
static void
black_text_text_release(gs_text_enum_t *pte, client_name_t cname)
{
black_text_text_enum_t *penum = (black_text_text_enum_t *)pte;
gs_text_enum_t * child = penum->child;
child->procs->release(child, cname);
gx_default_text_release(pte, cname);
}
The 'release' method is very slightly different, because we need to free the numerator, so we call 'gx_default_text_release'
Now, finally, we can define the 'text_begin' device method, the first thing we do is a convenience, we define a 'gs_text_enum_procs' instance which is initialised to point to all the text enumerator methods we defined above:
static const gs_text_enum_procs_t black_text_text_procs = {
black_text_text_resync, black_text_text_process,
black_text_text_is_width_only, black_text_text_current_width,
black_text_text_set_cache, black_text_text_retry,
black_text_text_release
};
So on to the text_begin method:
/* The device method which we do actually need to define.
*/
int black_text_text_begin(gx_device *dev, gs_imager_state *pis, const gs_text_params_t *text,
gs_font *font, gx_path *path, const gx_device_color *pdcolor, const gx_clip_path *pcpath,
gs_memory_t *memory, gs_text_enum_t **ppte)
{
black_text_text_enum_t *penum;
int code;
gs_text_enum_t *p;
rc_alloc_struct_1(penum, black_text_text_enum_t, &st_black_text_text_enum, memory,
return_error(gs_error_VMerror), "black_text_text_begin");
penum->rc.free = rc_free_text_enum;
code = gs_text_enum_init((gs_text_enum_t *)penum, &black_text_text_procs,
dev, pis, text, font, path, pdcolor, pcpath, memory);
if (code < 0) {
gs_free_object(memory, penum, "black_text_text_begin");
return code;
}
*ppte = (gs_text_enum_t *)penum;
code = default_subclass_text_begin(dev, pis, text, font, path, pdcolor, pcpath, memory, &p);
if (code < 0) {
gs_free_object(memory, penum, "black_text_text_begin");
return code;
}
penum->child = p;
return 0;
}
This uses library macros to create and initialise the text enumerator. Text enumerators are reference counted (and garbage collected.....) so we use the rc_alloc_struct family of macros, the '1' is the initial reference count that we want to have. We then call 'gs_text_enum_init' to initialise the newly created structure, passing in the text procs we just created as one of the arguments.
We then set the returned enumerator to point to the newly created text enumerator. Finally we pass the 'text_begin' method on to the child device using the 'default_subclass_text_begin' method and we store the returned text enumerator in the child pointer of our own enumerator.
At this point the code should compile and run properly, but it won;t actually do anything yet. For that we need to modify the current colour before we run the text. Fortunately we don't need to deal with the graphics state, the text_begin method is given the colour index to be used so all we need to do is alter that. We do, however, have to cater for what the device thinks 'black' actually is, but there are graphics library calls to deal with both finding that information and setting a colour index from it:
int black_text_text_begin(gx_device *dev, gs_imager_state *pis, const gs_text_params_t *text,
gs_font *font, gx_path *path, const gx_device_color *pdcolor, const gx_clip_path *pcpath,
gs_memory_t *memory, gs_text_enum_t **ppte)
{
black_text_text_enum_t *penum;
int code;
gs_text_enum_t *p;
/* Set the colour index in 'pdcolor' to be whatever the device thinks black shoudl be */
set_nonclient_dev_color((gx_device_color *)pdcolor, gx_device_black((gx_device *)dev));
That concludes the worked example and the documentation on device subclassing.