Difference: DeviceMethodsProposal (3 vs. 4)

Revision 42017-01-10 - ChrisLiddell

Line: 1 to 1
 
META TOPICPARENT name="WebHome"

Device Methods Tidy up Proposal

Line: 11 to 11
  "finish_copydevice" does not do what its name suggests. Rather it initialises a
newly created device. Thus I suggest changing it to "initialize".



Changed:
<
<
Every device method to take a graphics state parameter:

Not much to say on this: we've encountered enough cases where not having
access to a gstate in a given device method has proven problematic.



Further consolidation (as we are already making incompatible changes):

We have a number of device methods which do variations (some very minor, some
less so) of the same operations. For example, copy_mono, copy_color, copy_alpha
etc.

I would propose that for as many of these cases as is reasonable, we merge the
logically similar method into a single method, which would take a "variant"
parameter. The "variant" would be an enumerated type. For example, the methods:
'fill_trapezoid', 'fill_parallelogram', 'fill_triangle', 'fill_rectangle' and
'fill_rectangle_hl_color' would be merged into a single method 'fill_shape'.
The 'variant' parameter would differentiate between the primitive shapes
available, the '_hl_color' would be differentiated by passing in a valid
pointer to a high level color structure (and NULL otherwise).


In a few other cases, we can simply drop methods in favour of the more
flexible variants (added later to the API). The two examples of this are:
get_bits/get_band/get_bits_rectangle - where get_bits_rectangle will
cover all the requirements of the earlier two; and
strip_copy_rop2/strip_copy_rop - where strip_copy_rop2 does everything
that strip_copy_rop does.


In this category, merging all the transparency calls:
begin_transparency_group
begin_transparency_mask
end_transparency_group
end_transparency_mask
push_transparency_state
pop_transparency_state

into a single 'transparency' method, with a 'variant' and an opaque pointer
for those cases that require data passing through (push state).


By following this approach now, and hopefully as we move forward, we get a
smaller, but more flexible API, which allows for additional features in the
future without the number of methods exploding again. As an example, if we
found the need for a filled ellipse primitive, currently we would have to
add a 'fill_ellipse' (and possibly 'fill_ellipse_hl_color') method. In the
scheme proposed above, we'd simple add a new variant to an enumerated type.


The initial list of such consolidations is:
copy_mono/copy_color/copy_alpha/copy_planes/copy_alpha_hl_color
get_bits/get_band/get_bits_rectangle
fill_trapezoid/fill_parallelogram/fill_triangle/fill_rectangle/fill_rectangle_hl_color
fill_linear_color_trapezoid/fill_linear_color_triangle(/fill_linear_color_scanline)
strip_copy_rop2/strip_copy_rop
begin_transparency_group/begin_transparency_mask
end_transparency_group/end_transparency_mask
push_transparency_state/pop_transparency_state




Finally:

Reorder the methods so they are logically grouped (rather than the current
ordered by the time of their introduction). For example, open_device,
finish_copydevice (or whetever we call it), get_params, put_params,
get_hardware_params, dev_spec_op and probably others, would be grouped
together as those relating to device management/configuration.



>
>
Every device method to take a graphics state parameter:

Not much to say on this: we've encountered enough cases where not having
access to a gstate in a given device method has proven problematic.



Further consolidation (as we are already making incompatible changes):

We have a number of device methods which do variations (some very minor, some
less so) of the same operations. For example, copy_mono, copy_color, copy_alpha
etc.

I would propose that for as many of these cases as is reasonable, we merge the
logically similar method into a single method, which would take a "variant"
parameter. The "variant" would be an enumerated type. For example, the methods:
'fill_trapezoid', 'fill_parallelogram', 'fill_triangle', 'fill_rectangle' and
'fill_rectangle_hl_color' would be merged into a single method 'fill_shape'.
The 'variant' parameter would differentiate between the primitive shapes
available, the '_hl_color' would be differentiated by passing in a valid
pointer to a high level color structure (and NULL otherwise).


In a few other cases, we can simply drop methods in favour of the more
flexible variants (added later to the API). The two examples of this are:
get_bits/get_band/get_bits_rectangle - where get_bits_rectangle will
cover all the requirements of the earlier two; and
strip_copy_rop2/strip_copy_rop - where strip_copy_rop2 does everything
that strip_copy_rop does.


In this category, merging all the transparency calls:
begin_transparency_group
begin_transparency_mask
end_transparency_group
end_transparency_mask
push_transparency_state
pop_transparency_state

into a single 'transparency' method, with a 'variant' and an opaque pointer
for those cases that require data passing through (push state).


By following this approach now, and hopefully as we move forward, we get a
smaller, but more flexible API, which allows for additional features in the
future without the number of methods exploding again. As an example, if we
found the need for a filled ellipse primitive, currently we would have to
add a 'fill_ellipse' (and possibly 'fill_ellipse_hl_color') method. In the
scheme proposed above, we'd simple add a new variant to an enumerated type.


The initial list of such consolidations is:
copy_mono/copy_color/copy_alpha/copy_planes/copy_alpha_hl_color
get_bits/get_band/get_bits_rectangle
strip_copy_rop2/strip_copy_rop
begin_transparency_group/begin_transparency_mask
end_transparency_group/end_transparency_mask
push_transparency_state/pop_transparency_state
fill_trapezoid/fill_parallelogram/fill_triangle/fill_rectangle/fill_rectangle_hl_color
fill_linear_color_trapezoid/fill_linear_color_triangle(/fill_linear_color_scanline)



Finally:

Reorder the methods so they are logically grouped (rather than the current
ordered by the time of their introduction). For example, open_device,
finish_copydevice (or whetever we call it), get_params, put_params,
get_hardware_params, dev_spec_op and probably others, would be grouped
together as those relating to device management/configuration.



  New Addition:
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright 2014 Artifex Software Inc