/** -*-C-*-ish
    Kaya standard library
    Copyright (C) 2004, 2005, 2006, 2007 Edwin Brady, Chris Morris

    This file is distributed under the terms of the GNU Lesser General
    Public Licence. See COPYING for licence.
*/
"<summary>Image manipulation</summary>
<prose>This module interfaces to the GD library for creating and editing JPEG and PNG images. It also provides a displayPage function so that the generated images may be easily output by webapps.</prose>
<prose>See the <link url='http://kayalang.org/cgi/shape.cgi'>Shape CGI</link> for an example of the use of this module on the web.</prose>"
module Image;

import Prelude;
import IO;
import Binary;
import Webapp;

%include "image_glue.h";
%imported "image_glue";
%link "gd";

"<summary>Image data.</summary>
<prose>An editable image</prose>"
abstract data Image = Image(Ptr imptr,Int xsize, Int ysize);

"<summary>Web image data</summary>
<prose>An uneditable image ready to be displayed on the web</prose>"
abstract data WebImage = WebImage(Binary img, String ctype, [(String,String)] headers);

"<summary>Drawing colour.</summary>
<prose>A drawing colour</prose>"
abstract data Colour = Col(Int col);

"<summary>Drawing font.</summary>
<prose>A drawing font</prose>"
abstract data Font = Font(Ptr fontptr);

"<summary>Arc fill styles.</summary>
<prose>Fill styles for arcs.</prose>"
public data ArcStyle = Arc | Chord | Pie | NoFill | Edged;

type Color = Colour; // Euw

foreign "image.o" {
    Ptr do_createImage(Int x,Int y, Bool tc) = createImage;
    Void do_destroyImage(Ptr imptr) = destroyImage;
    Image do_createImageFromPNG(Ptr f) = createImageFromPNG;
    Image do_createImageFromJPEG(Ptr f) = createImageFromJPEG;
    Int imageColourAllocate(Ptr ptr, Int r, Int g, Int b, Int a) 
	= imageColourAllocate;

    Ptr fontGetSmall() = fontGetSmall;
    Ptr fontGetLarge() = fontGetLarge;
    Ptr fontGetMediumBold() = fontGetMediumBold;
    Ptr fontGetGiant() = fontGetGiant;
    Ptr fontGetTiny() = fontGetTiny;

    Void imageString(Ptr ptr, Ptr font, Int x, Int y, String str,
		     Int col, Bool up) = imageString;
    Void imageLine(Ptr ptr, Int x1, Int y1, Int x2, Int y2, Int col)
	= imageLine;
    Void imageDashedLine(Ptr ptr, Int x1, Int y1, Int x2, Int y2, Int col)
	= imageDashedLine;
    Void imageRectangle(Ptr ptr, Int x1, Int y1, Int x2, Int y2, 
			Int col, Bool filled) = imageRectangle;
    Void imageSetPixel(Ptr ptr, Int x, Int y, Int col) = imageSetPixel;
    Void imageDrawPoly(Ptr ptr,[(Int,Int)] points, Int col, Bool filled)
	= imageDrawPoly;

    Void imageArc(Ptr ptr, Int cx, Int cy, Int w,Int h, Int start, Int end,
		  Int col, [ArcStyle] style, Bool filled) = imageArc;
    Void imageCopy(Ptr dest, Ptr src, Int dstx, Int dsty, 
		   Int srcx, Int srcy, Int w, Int h) = imageCopy;

    Void imageCopyResized(Ptr dest, Ptr src, Int dstx, Int dsty,
			  Int srcx, Int srcy, Int destw, Int desth,
			  Int srcw, Int srch) = imageCopyResized;

    Void imageWritePNG(Ptr ptr, Ptr f) = imageWritePNG;
    Void imageWriteJPEG(Ptr ptr, Ptr f, Int qual) = imageWriteJPEG;
    Binary imageGetPNG(Ptr ptr) = imageGetPNG;
    Binary imageGetJPEG(Ptr ptr, Int qual) = imageGetJPEG;
}

"<summary>Colour value out of range</summary>
<prose>This Exception is thrown if a colour red, green or blue component is outside the range 0-255, or the alpha component is outside the range 0-127.</prose>"
Exception ColourOutOfRange();

/// Image creation

"<argument name='x'>Image width in pixels</argument>
<argument name='y'>Image height in pixels</argument>
<argument name='truecolour'>Is the image true colour (optional, defaulting to false)</argument>
<summary>Create a new image</summary>
<prose>Create a new image with the specified dimensions and colour.</prose>
<related><functionref index='1'>create</functionref></related>"
public Image create(Int x, Int y, Bool truecolour=false) {
    imgdata = do_createImage(x,y,truecolour);
    return Image(imgdata,x,y);
}

"<argument name='img'>Destroy an image</argument>
<summary>Destroy an image</summary>
<prose>Destroy an image.</prose>"
public Void destroy(Image img) {
    do_destroyImage(img.imptr);
}

"<argument name='img'>The image</argument>
<summary>Get image width</summary>
<prose>Get the width of an image in pixels</prose>
<related><functionref>height</functionref></related>"
public Int width(Image img) = img.xsize;
"<argument name='img'>The image</argument>
<summary>Get image height</summary>
<prose>Get the height of an image in pixels</prose>
<related><functionref>width</functionref></related>"
public Int height(Image img) = img.ysize;

"<summary>Image format</summary>
<prose>What data format is used for the image. JPEG is better for photographic images, PNG for abstract graphics.</prose>"
public data ImageType = PNG | JPEG;

"<argument name='fname'>The filename of the image to load</argument>
<argument name='ty'>Whether the image to be loaded is PNG or JPEG</argument>
<summary>Create an image from a file</summary>
<prose>Loads an image from a file and returns the resulting <dataref>Image</dataref>.</prose>
<related><functionref>create</functionref></related>"
public Image create(String fname, ImageType ty) {
    f = open(fname,[Read,Binary]);
    case ty of {
	PNG -> img = do_createImageFromPNG(ptr(f));
      | JPEG -> img = do_createImageFromJPEG(ptr(f));
    }
    close(f);
    return img;
}

"<argument name='img'>The image</argument>
<argument name='r'>The red channel (0..255)</argument>
<argument name='g'>The green channel (0..255)</argument>
<argument name='b'>The blue channel (0..255)</argument>
<argument name='a'>The alpha channel (0..127). 127 represents full transparency. This argument may be omitted for a default of 0 (fully opaque)</argument>
<summary>Allocate a colour.</summary>
<prose>Allocate the specified colour for use in the image.</prose>"
public Colour makeColour(Image img, Int r, Int g, Int b, Int a = 0) {
    if (r<0 || r>255 || g<0 || g>255 || b<0 || b>255 || a<0 || a>127) {
	throw(ColourOutOfRange());
    }
    return Col(imageColourAllocate(img.imptr, r, g, b, a));
}

/// Fonts and text
"<summary>Small font</summary>
<prose>A small font</prose>"
public Font small() = Font(fontGetSmall());
"<summary>Large font</summary>
<prose>A large font</prose>"
public Font large() = Font(fontGetLarge());
"<summary>Medium bold font</summary>
<prose>A medium and bold font</prose>"
public Font mediumBold() = Font(fontGetMediumBold());
"<summary>Giant font</summary>
<prose>A giant font</prose>"
public Font giant() = Font(fontGetGiant());
"<summary>Tiny font</summary>
<prose>A tiny font</prose>"
public Font tiny() = Font(fontGetTiny());

"<argument name='img'>The image</argument>
<argument name='font'>The font to use (e.g. <functionref>small</functionref>)</argument>
<argument name='x'>The left-right position of the start of the text</argument>
<argument name='y'>The top-bottom position of the start of the text</argument>
<argument name='str'>The text to add</argument>
<argument name='col'>The colour of the text</argument>
<argument name='up'>Normally text is drawn left to right. If this parameter is true, it will be drawn bottom to top instead.</argument>
<summary>Draw a text string.</summary>
<prose>Writes a text string at the given location.</prose>"
public Void drawString(Image img, Font font, Int x, Int y,
		       String str, Colour col, Bool up = false) {
    imageString(img.imptr, font.fontptr, x,y,str,col.col, up);
}

/// Drawing

"<argument name='img'>The image</argument>
<argument name='x1'>X coordinate of first endpoint</argument>
<argument name='y1'>Y coordinate of first endpoint</argument>
<argument name='x2'>X coordinate of second endpoint</argument>
<argument name='y2'>Y coordinate of second endpoint</argument>
<argument name='col'>Colour of the line</argument>
<summary>Draw a line.</summary>
<prose>Draws a line on the image from (<variable>x1</variable>,<variable>y1</variable>) to (<variable>x2</variable>,<variable>y2</variable>).</prose>
<related><functionref>dashedLine</functionref></related>
<related><functionref>rectangle</functionref></related>"
public Void line(Image img, Int x1, Int y1, Int x2, Int y2, Colour col) {
    imageLine(img.imptr, x1, y1, x2, y2, col.col);
}

"<argument name='img'>The image</argument>
<argument name='x1'>X coordinate of first endpoint</argument>
<argument name='y1'>Y coordinate of first endpoint</argument>
<argument name='x2'>X coordinate of second endpoint</argument>
<argument name='y2'>Y coordinate of second endpoint</argument>
<argument name='col'>Colour of the line</argument>
<summary>Draw a dashed line.</summary>
<prose>Draws a dashed line on the image from (<variable>x1</variable>,<variable>y1</variable>) to (<variable>x2</variable>,<variable>y2</variable>).</prose>
<related><functionref>line</functionref></related>
<related><functionref>rectangle</functionref></related>"
public Void dashedLine(Image img, Int x1, Int y1, 
			Int x2, Int y2, Colour col) {
    imageDashedLine(img.imptr, x1, y1, x2, y2, col.col);
}

"<argument name='img'>The image</argument>
<argument name='x1'>X coordinate of first corner</argument>
<argument name='y1'>Y coordinate of first corner</argument>
<argument name='x2'>X coordinate of opposite corner</argument>
<argument name='y2'>Y coordinate of opposite corner</argument>
<argument name='col'>Colour of the rectangle's border</argument>
<argument name='filled'>If this is true, the rectangle will be filled with the same colour as the border.</argument>
<summary>Draw a rectangle.</summary>
<prose>Draws a rectangle with opposite corners at (<variable>x1</variable>,<variable>y1</variable>) and (<variable>x2</variable>,<variable>y2</variable>).</prose>
<related><functionref>dashedLine</functionref></related>
<related><functionref>ellipse</functionref></related>
<related><functionref>line</functionref></related>
<related><functionref>poly</functionref></related>"
public Void rectangle(Image img, Int x1, Int y1, 
		      Int x2, Int y2, Colour col,
		      Bool filled = false) {
    imageRectangle(img.imptr, x1, y1, x2, y2, col.col, filled);
}

"<argument name='img'>The image</argument>
<argument name='x'>The X coordinate of the pixel</argument>
<argument name='y'>The Y coordinate of the pixel</argument>
<argument name='col'>The colour to paint the pixel</argument>
<summary>Set a pixel's colour.</summary>
<prose>Sets the colour of the specified pixel.</prose>"
public Void setPixel(Image img, Int x, Int y, Colour col) {
    imageSetPixel(img.imptr, x, y, col.col);
}

"<argument name='img'>The image</argument>
<argument name='points'>A list of pairs (in X,Y order) giving the corners of the polygon.</argument>
<argument name='col'>Colour of the polygon's border</argument>
<argument name='filled'>If this is true, the polygon will be filled with the same colour as the border.</argument>
<summary>Draw a polygon.</summary>
<prose>Draws a polygon with the specified corners.</prose>
<related><functionref>ellipse</functionref></related>
<related><functionref>rectangle</functionref></related>"
public Void poly(Image img, [(Int,Int)] points, Colour col, 
		 Bool filled = false)
{
    imageDrawPoly(img.imptr,points,col.col,filled);
}

"<argument name='img'>The image</argument>
<argument name='cx'>The X coordinate of the centre of the ellipse</argument>
<argument name='cy'>The Y coordinate of the centre of the ellipse</argument>
<argument name='w'>The width of the ellipse</argument>
<argument name='h'>The height of the ellipse</argument>
<argument name='start'>The starting angle (in degrees measured clockwise from rightwards)</argument>
<argument name='end'>The ending angle (in degrees measured clockwise from rightwards)</argument>
<argument name='col'>Colour of the arc</argument>
<argument name='filled'>Whether the arc is filled (defaults to false)</argument>
<argument name='style'>If the arc is filled, a list of <dataref>ArcStyle</dataref>s to apply.</argument>
<summary>Draw an arc of an ellipse.</summary>
<prose>Draw an arc of an ellipse, optionally filled, with the specified parameters.</prose>
<related><functionref>ellipse</functionref></related>"
public Void arc(Image img, Int cx, Int cy, 
		Int w, Int h, Int start, Int end, Colour col,
		Bool filled = false,
		[ArcStyle] style = [Arc])
{
    imageArc(img.imptr,cx,cy,w,h,start,end,col.col,style,filled);
}

"<argument name='img'>The image</argument>
<argument name='cx'>The X coordinate of the centre of the ellipse</argument>
<argument name='cy'>The Y coordinate of the centre of the ellipse</argument>
<argument name='w'>The width of the ellipse</argument>
<argument name='h'>The height of the ellipse</argument>
<argument name='col'>Colour of the ellipse</argument>
<argument name='filled'>Whether the ellipse is filled (defaults to false)</argument>
<summary>Draw an ellipse.</summary>
<prose>Draw an ellipse at the specified position.</prose>
<related><functionref>arc</functionref></related>
<related><functionref>poly</functionref></related>
<related><functionref>rectangle</functionref></related>"
public Void ellipse(Image img, Int cx, Int cy, 
		    Int w, Int h, Colour col,
		    Bool filled = false) 
{
    arc(img,cx,cy,w,h,0,360,col,filled,[Arc]);
}

/// Copying/resizing

"<argument name='dest'>Destination image</argument>
<argument name='src'>Source image</argument>
<argument name='dstx'>Destination left edge</argument>
<argument name='dsty'>Destination top edge</argument>
<argument name='srcx'>Source left edge</argument>
<argument name='srcy'>Source top edge</argument>
<argument name='w'>Width of area to copy</argument>
<argument name='h'>Height of area to copy</argument>
<summary>Copy a portion of an image.</summary>
<prose>Copy a portion of an image from one image to another.</prose>
<related><functionref>copyResized</functionref></related>"
public Void copy(Image dest, Image src, Int dstx, Int dsty, 
		 Int srcx, Int srcy, Int w, Int h)
{
    imageCopy(dest.imptr,src.imptr,dstx,dsty,srcx,srcy,w,h);
}

"<argument name='dest'>Destination image</argument>
<argument name='src'>Source image</argument>
<argument name='dstx'>Destination left edge</argument>
<argument name='dsty'>Destination top edge</argument>
<argument name='srcx'>Source left edge</argument>
<argument name='srcy'>Source top edge</argument>
<argument name='destw'>Width of area to copy in to</argument>
<argument name='desth'>Height of area to copy in to</argument>
<argument name='srcw'>Width of area to copy out of</argument>
<argument name='srch'>Height of area to copy out of</argument>
<summary>Copy and resize a portion of an image.</summary>
<prose>Copy a portion of an image from one image to another, resizing the copied area to fit within a particular destination rectangle.</prose>
<related><functionref>copy</functionref></related>"
public Void copyResized(Image dest, Image src, Int dstx, Int dsty, 
			Int srcx, Int srcy, Int destw, Int desth,
			Int srcw, Int srch)
{
    imageCopyResized(dest.imptr,src.imptr,dstx,dsty,srcx,srcy,
				  destw,desth,srcw,srch);
}

/// Output

"<argument name='img'>The image</argument>
<argument name='file'>The file name to write to. This argument may be omitted to use standard output, which is useful in CGI scripts - call <functionref>CGI::flush</functionref> first to ensure the headers have been sent.</argument>
<summary>Output a PNG.</summary>
<prose>Outputs a PNG from the image. This function should not be used with standard output in the webapp model - use <functionref>webPNG</functionref> instead.</prose>
<related><functionref>makeJPEG</functionref></related>"
public Void makePNG(Image img, String file = "") {
    if (file=="") {
	f = stdout;
    } else {
	f = open(file,[Write,Binary]);
    }
    imageWritePNG(img.imptr, ptr(f));
    if (file!="") { close(f); }
}

"<argument name='img'>The image</argument>
<summary>Get PNG data</summary>
<prose>Returns a Binary object containing the image data in PNG format.</prose>
<related><functionref>getJPEG</functionref></related>"
public Binary getPNG(Image img) {
  return imageGetPNG(img.imptr);
}

"<argument name='img'>The image</argument>
<argument name='qual'>The image quality (0..95). Alternatively, any negative number will use the default output quality.</argument>
<argument name='file'>The file name to write to. This argument may be omitted to use standard output, which is useful in CGI scripts - call <functionref>CGI::flush</functionref> first to ensure the headers have been sent.</argument>
<summary>Output a JPEG.</summary>
<prose>Outputs a JPEG from the image. This function should not be used with standard output in the webapp model - use <functionref>webJPEG</functionref> instead.</prose>
<related><functionref>makePNG</functionref></related>"
public Void makeJPEG(Image img, Int qual = -1, String file = "") {
    if (file=="") {
	f = stdout;
    } else {
	f = open(file,[Write,Binary]);
    }
    imageWriteJPEG(img.imptr, ptr(f), qual);
    if (file!="") { close(f); }
}

"<argument name='img'>The image</argument>
<argument name='qual'>The image quality (0..95). Alternatively, any negative number will use the default output quality.</argument>
<summary>Get JPEG data</summary>
<prose>Returns a Binary object containing the image data in JPEG format.</prose>
<related><functionref>getPNG</functionref></related>"
public Binary getJPEG(Image img, Int qual=-1) {
  return imageGetJPEG(img.imptr,qual);
}


"<argument name='img'>The image</argument>
<argument name='extraheaders'>Any additional HTTP headers to send with the image</argument>
<summary>Get a PNG for webmain</summary>
<prose>Returns a PNG image suitable for returning from a webapp's <code>webmain</code> function.</prose>
<related><functionref>webJPEG</functionref></related>"
public WebImage webPNG(Image img, [(String,String)] extraheaders) {
  return WebImage(getPNG(img),"image/png",extraheaders);
}

"<argument name='img'>The image</argument>
<argument name='extraheaders'>Any additional HTTP headers to send with the image</argument>
<argument name='qual'>The image quality (0..95). Alternatively, any negative number will use the default output quality.</argument>
<summary>Get a JPEG for webmain</summary>
<prose>Returns a JPEG image suitable for returning from a webapp's <code>webmain</code> function.</prose>
<related><functionref>webPNG</functionref></related>"
public WebImage webJPEG(Image img, [(String,String)] extraheaders, Int qual=-1) {
  return WebImage(getJPEG(img,qual),"image/jpeg",extraheaders);
}

"<argument name='image'>A <dataref>WebImage</dataref> produced with <functionref>webPNG</functionref> or <functionref>webJPEG</functionref>.</argument>
<summary>Display function for webapps</summary>
<prose>Display an image via HTTP. This function should be called automatically by a web application when the return type of <code>webmain</code> is <dataref>WebImage</dataref>. Calling this function directly is generally only necessary for debugging purposes.</prose>
<related><moduleref>Webapp</moduleref></related>"
public Void displayPage(WebImage image) {
  push(image.headers,("Content-type",image.ctype));
  displayPage(image.img,image.headers);
}