-------------------------------------------------------------
-- XFILL Constructed by Greg Izzo
--   Copyright (c) 2000 [Version 1.01]
-------------------------------------------------------------
-- 
xtra Xfill -- flood filling (paint bucket-like operation) on the stage
new object me
      -- Create a new Xfill object
fill object me, integer X, integer Y, list rect 
      -- Initiate the fill starting at location X,Y.
      -- the rectangle defines the fill area
      -- Returns [Red, Green, Blue] the color of location x,y
		error list:
			no error: returns a list of the Red Green and Blue value at the fill point [r,g,b]
			-10: the X and y coord are outside the rectangle passed in
			-1 : the x and y coord are off screen
			-2:  failed to create temp area for internal mask
			-3:  failed to get the base address for the internal mask
			-4:  failed to create the new Gworld for holding the fill color region

SetFillColor object me, integer X, integer Y 
      -- Sets the fill color based on an X,Y location on the screen 
      -- Returns [Red, Green, Blue]
      --   or -1 if x,y is off screen
SetFillColorRGB object me, RED, GREEN, BLUE 
      -- Sets the fill color to the RED, GREEN, BLUE value passed in 
Compact object me
      -- MAC ONLY - calls CompactMem(maxSize)
Purge object me
      -- MAC ONLY - calls PurgeMem(maxSize)
drawLine object me, integer startX, integer startY, integer endX, integer endY, integer penWidth 
      -- (win) draw a line (startx, starty) to (endx, endy) with pen width of penWidth pixels.

The floodfill Xtra works by filling a color into Director's off-screen buffer, 
then copying that onto the stage. The filled region on the screen behaves the same 
as Director's "trails" ink. If you move a sprite over the flood-filled region, 
the poured color will be erased. The "drawLine" routine behaves the same way. 
To retain the image, capture the stage to a castmember. 
This was sufficient for the project that this Xtra was created for.

Below is a typical way to use it in lingo:

myObj = new(xtra "xfill") -- create an instance of the Xtra

Whatcolor = setfillcolor(myObj, the mouseh, the mousev) 
--- sets the fill/draw color to the color of the screen location point(the mouseh, the mousev)
--- The Xtra return a list containing the RED, GREEN and BLUE values for the color it has found.
--- so, whatcolor equals [<red value>, <green value>, <blue value>]

Whatcolor = setFillcolorRGB(myObj, 255,0,0) 
-- sets the fill/draw color to the color whose red value = 255, green value = 0, and blue value = 0
-- The Xtra return a list containing the RED, GREEN and BLUE values selected color.
-- so, Whatcolor is set to the list [255,0,0]

Whatcolor = fill(myObj, 100,105 mousev, rect(50,50,200,200))
-- Using the color set by either "setfillcolor" or "setfillcolorrgb", the filling starts at screen location
-- point(100,105), and expands to boundary rectangle which was given as rect(50,50,200,200)
-- Whatcolor is set to a list that tells what the final color was at the starting point (point(100,105))

successflag = drawline(myObj, 100,100,200,200, 3)
-- draws a line from point(100,100) to point(200,200) using a pen size of 3. 
-- If successful, the successflag = 1
-- other values returned:
--  -1 = couldn't access director's offscreen buffer
--  -2 = the start location is not on screen
--  -3 = the end location is not on screen
--  -4 = couldn't access director's stage
--  -5 = couldn't access info about director's stage
-- -11 = couldn't access info about director's offscreen buffer


myobj = 0
-- get rid of the instance of the xtra


-----------------------------------------------------------------


notes:

The "Compact" and "Purge" commands are not related to the flood filling functionality. 
They were added in an attempt de-fragement memory on the mac. 
Ultimately, although they did change memory, they didn't solve the memory fragmentation issues 
that our project was experiencing.

This Xtra is being made available "as-is", which means that there is no support for it and you will 
be using it at your own risk. It was tested as part of a larger product and appears to be 
stable and does not appear to contain any memory leaks. It is meant as a free piece of software
for the community to use. It is not to be re-sold. It may be distributed freely.

I hope it proves helpful.

Greg Izzo -  gregizzo@randomneuraldischarge.com