Re: [AD] al_draw_polygon_with_holes, etc.

[Peter Wang <novalazy@xxxxxxxxxx>]

On Sun, 14 Apr 2013 18:56:37 -0400, SiegeLord <slabode@xxxxxxxxxx> wrote:
> On 04/14/2013 09:45 AM, Peter Wang wrote:
> > How about:
> >
> >    * al_draw_polygon_with_holes => al_draw_multiple_polygons
> >      The current name is just wrong.
> 
> I think it should just be removed, as it does indeed appear to simply 
> draw multiple polygons

Fine by me.

> >
> >    * al_draw_filled_polygon_with_holes => al_draw_cutout_polygon
> >      I think you can't cut out a polygon unless it is filled,
> >      though it breaks the "filled" pattern.
> 
> The old name is pretty self-explanatory, even if a bit redundant. I 
> certainly don't think "cutout" explains what it does...
> 

Eh, ok.  "Hole" just sounds roundish to me.

> > Furthermore, wouldn't it be simpler to understand if the 'holes' array
> > is replaced by an array of the number of vertices in each respective
> > polygon?  This also affects al_triangulate_polygon.
> 
> The 'holes' array is a horrible name for what it represents (as it also 
> contains the polygon outline). al_triangulate_polygon uses 'splits' 
> which is marginally better. Also it is redundant with the 'vertex_count' 
> attribute which will always equal the last entry in the 'holes' array.
> 
> I'd prefer for 'vertex_count' to be gone and 'holes' given a better 
> name. Whether it contains relative (number of vertices per outline) or 
> absolute (current behavior) doesn't matter to me much... the relative 
> indexing semantic is more consistent with most of Allegro's API (e.g. 
> creating sub bitmaps takes width and height, and not the bottom right 
> corner), but the absolute indexing semantic is not without precedent 
> either (al_draw_prim/rectangle/line ... my bad there for deviating from 
> the rest of the API when I made those functions).
> 

I don't think there's anything wrong with those examples.

How about:

    void al_draw_filled_polygon_with_holes(
	const float vertices[], const int vertex_counts[],
	ALLEGRO_COLOR color);

Draws a filled polygon with zero or more other polygons subtracted
from it - the holes.

* vertices - interleaved array of (x, y) vertices coordinates
  for each of the polygons, including the holes.

* vertex_counts - number of vertices for each polygon.
  The number of vertices in the filled polygon is given by
  vertex_counts[0] and must be at least three.
  Subsequent elements indicate the number vertices in each hole.
  The array must be terminated with an element with value zero.


> >
> > Is there a real need for the split_stride parameter to
> > al_triangulate_polygon?  I suggest to drop it.
> 
> Seems a bit excessive, yes.
> 

Peter