//--file: CIUPrimitive.java------------------------------------------
//
package starwave.app.poll.imageutils;

/** 
 *
 * An IU primitive,  capable of providing enough information to
 * be drawn,  as well as the operations "translate", "rotate" and
 * "scale".
 *
 * "Translate" is implemented in this class while "rotate" and "scale"
 * must be provided by extended classes.
 *
 * Implementation is such that the usage can be: 
 *
 * 
 *   CIUPrimitive p = new CIURectangle( 20, 10).translate(2, 15).scale( 2.0 ); 
 * 
 *
 * which will construct a 20x10 rectangle,  translate this rectangle
 * to coordinates 2,15,  and then scale it by a factor of 2.
 *
 * The primitive is constructed such that it's "handle"  (for translating) 
 * is the upper left hand corner of the primitive's bounding box,  and this 
 * is originally located at the coordinate (0,0) of the graphics context.
 * For example,  the following calls:  
 *
 * 
 *         CIUGraphicsContext gc = new CIUGraphicsContext( 12, 9 );     
 *         CIUPrimitive p = new CIURectangle(6, 3).translate(1, 2);     
 *         gc.draw( p );                                                
 * 
 *
 * will result in a rectangle positioned here ('0'=bg color, 'X'=rectangle color):
 *
 * 
 *         000000000000 
 *         000000000000 
 *         0XXXXXX00000 
 *         0XXXXXX00000 
 *         0XXXXXX00000 
 *         000000000000 
 * 
 *
 */
public abstract class CIUPrimitive
{
    /** The width of the graphic */
    protected int m_w;

    /** The height of the graphic */
    protected int m_h;

    /** The x translation */
    protected int m_xOffset;

    /** The y translation */
    protected int m_yOffset;
    
    /** The primitive's rotation in degrees */
    protected double m_rotation;

    /** Textured or solid color? */
    protected boolean m_textured; 



    /** *************************************************************
     *
     * Construct a IUPrimitive
     *
     * @param w The width of the primitive
     * @param h The height of the primitive
     *
     */
    public CIUPrimitive( int w, int h )
    {
	    this.m_w = w;
	    this.m_h = h;
	    this.m_xOffset = 0;
	    this.m_yOffset = 0;
	    this.m_rotation = 0.0;
	    this.m_textured = false;
    }


    /** *************************************************************
     *
     * Accessors required for drawing
     *
     */
    public int height()          { return m_h;        }
    public int width()           { return m_w;        }
    public int transX()          { return m_xOffset;  }
    public int transY()          { return m_yOffset;  }
    public boolean textured()    { return m_textured; }



    /** ************************************************************
     *
     * Takes any angle in (in degrees) and returns a positive 
     * angle in the range [0..360].
     *
     * @param degree The angle in degrees
     * @returns double The angle in range [0..360]
     *
     */
    protected double getAngle( double degree )
    {
         degree = ( degree % 360.0 );
         return ( (degree>=0)?(degree):(360.0+degree) );
    }



    /** *************************************************************
     *
     * Is a particular pixel on?   Given a valid X/Y coordinate,
     * return an indicator indicating whether the pixel is on.
     *
     * @param x The x-coordinate of interest
     * @param x The y-coordinate of interest
     * @returns boolean indicating pixel on/off status
     *
     * @throws Exception If invalid pixel request is made.
     * @exception Exception If invalid pixel request is made.
     *
     */
    public abstract boolean pixelOn( int x, int y ) throws Exception;



    /** *************************************************************
     *
     * Color accessor - given an X/Y pair,  return a IUColor.
     * This works well for solid primitives,  but will involve
     * many LUT lookups for textured primitives.  The IUColor
     * returned for each coordinate needs to be looked up in the
     * color cube to get a valid index.
     *
     * @param x The x-coordinate of interest
     * @param x The y-coordinate of interest
     * @returns byte The index into the LUT for the color
     *
     * @throws Exception If invalid pixel request is made.
     * @exception Exception If invalid pixel request is made.
     *
     */
    public abstract byte color( int x, int y ) throws Exception;




    /** *************************************************************
     *
     * Translate the child relative to where it was before.
     * Return a CIUPrimitive.
     *
     * @param x The x-coordinate of interest
     * @param x The y-coordinate of interest
     * @returns CIUPrimitive this
     *
     */
    public CIUPrimitive translate( int x, int y )
    {
    	m_xOffset += x;
    	m_yOffset += y;
        return this;
    }




    /** *************************************************************
     *
     * Zero out the translation of the primitive
     *
     * @returns CIUPrimitive this
     *
     */
    public CIUPrimitive zero()
    {
	m_xOffset = 0;
    	m_yOffset = 0;
        return this;
    }




    /** *************************************************************
     *
     * Rotate - return a CIUPrimitive
     *
     * @param angle The angle to rotate through (in degrees)
     * @returns CIUPrimitive this
     *
     */
    public abstract CIUPrimitive rotate( double angle );




    /** *************************************************************
     *
     * Scale - return a CIUPrimitive
     *
     * @param scalar The scalar
     * @returns CIUPrimitive this
     *
     */
    public abstract CIUPrimitive scale( double scalar );




    /** *************************************************************
     *
     * toString: Convert the primitive to some sort of appropriate
     *    string representation.
     *
     * @returns String The string representation of the primitive
     *
     */
    public abstract String toString();





    /** *************************************************************
     *
     * Free up any system resources associated with this primitive
     *
     */
    public abstract void dispose();

}