ocaml-canvas 1.0.0 (latest)

Canvas manipulation functions

type t

An abstract type representing a canvas

Comparison and hash functions

In order to ease identification of canvas or building collections of canvas, the usual comparison and hash functions are provided. These functions simply operate on the canvas' unique ids. Also, standard structural and physical comparison operators can be used to compare canvases.

val compare : t -> t -> int

compare c1 c2 is equivalent to compare (getId c1) (getId c2)

val hash : t -> int

hash c returns a unique integer value for canvas c, which is computed as Hashtbl.hash (Canvas.getId c)

Creation

val createOnscreen : 
  ?autocommit:bool ->
  ?decorated:bool ->
  ?resizeable:bool ->
  ?minimize:bool ->
  ?maximize:bool ->
  ?close:bool ->
  ?title:string ->
  ?pos:(int * int) ->
  size:(int * int) ->
  unit ->
  t

createOnscreen ?autocommit ?decorated ?resizeable ?minimize ?maximize ?close ?title ?pos ~size () creates a windowed canvas of size size. The window title and position can be specified using the optional arguments title and pos. The window decorations, which are active by default, can be disabled using the optional arguments decorated, resizeable, minimize, maximize, and close. The decorated argument has a higher priority: if set to false, all other decoration arguments will be ignored (considered to be false), and all decorations will be removed from the window. The autocommit option, which is active by default, indicates whether the canvas should be automatically presented after each frame event. See Canvas.commit for more info on autocommit.

Exceptions:

Exception.Not_initialized if Backend.init was not called
Invalid_argument if either component of size is outside the range 1-32767

val createOffscreen : size:(int * int) -> unit -> t

createOffscreen ~size creates an offscreen canvas of size size

Exceptions:

Exception.Not_initialized if Backend.init was not called
Invalid_argument if either component of size is outside the range 1-32767

val createOffscreenFromImageData : ImageData.t -> t

createOffscreenFromImageData id creates an offscreen canvas with the contents of image data id

Exceptions:

Exception.Not_initialized if Backend.init was not called

val createOffscreenFromPNG : string -> t React.event

createOffscreen filename creates an offscreen canvas with the contents of PNG file filename. The returned event will be triggered once the image is loaded.

Exceptions:

Exception.Not_initialized if Backend.init was not called
Exception.Read_png_failed if the PNG file could not be read

Visibility

val show : t -> unit

show c makes the canvas c visible on screen. Does nothing on offscreen canvases.

val hide : t -> unit

hide c makes the canvas c invisible. Does nothing offscreen canvases.

val close : t -> unit

close c closes the canvas c, i.e. it permanently removes it from the screen and prevents it to receive events ; however it can still be used as an offscreen canvas. Does nothing on offscreen canvases.

Rendering

val commit : t -> unit

commit c informs the backend that the canvas has been modified and should be presented on screen. This is not necessary if the canvas has been created with autocommit set to true, as in this case the canvas will be automatically presented after each frame event. Note that it is also useless when using the Javascript backend ; however, to maintain consistent behavior between the various backends, do remember to use commit on any canvas created with autocommit set to false. Does nothing on offscreen canvases.

Configuration

val getId : t -> int

getId c returns the unique id of canvas c

val getSize : t -> int * int

getSize c returns the size of canvas c

val setSize : t -> (int * int) -> unit

setSize c size sets the size of canvas c

Exceptions:

Invalid_argument if either component of size is outside the range 1-32767

val getPosition : t -> int * int

getPosition c returns the position of canvas c. Returns (0, 0) when used on offscreen cavnas.

val setPosition : t -> (int * int) -> unit

setPosition c pos sets the position of canvas c. Does nothing on offscreen canvases.

State

val save : t -> unit

save c pushes the current state of canvas c onto the state stack

val restore : t -> unit

restore c pops the current state of canvas c from the state stack

Transformations

val setTransform : t -> Transform.t -> unit

setTransform c t sets the current transformation matrix of canvas c. The matrix t = { a, b, c, d, e, f } is of the following form:

a b 0
c d 0
e f 1

val transform : t -> Transform.t -> unit

transform c t apply the given arbitrary transformation to the current transformation matrix of canvas c

val translate : t -> Vector.t -> unit

translate c vec apply the given translation transform to the current transformation matrix of canvas c

val scale : t -> Vector.t -> unit

scale c vec apply the given scale transform to the current transformation matrix of canvas c

val shear : t -> Vector.t -> unit

shear c vec apply the given shear transform to the current transformation matrix of canvas c

val rotate : t -> float -> unit

rotate c theta apply the given rotation transform to the current transformation matrix of canvas c

Style

val getLineWidth : t -> float

getLineWidth c returns the current line width of canvas c

val setLineWidth : t -> float -> unit

setLineWidth c w sets the current line width of canvas c to w

val getLineJoin : t -> Join.t

getLineJoin c returns the current line join type of canvas c

val setLineJoin : t -> Join.t -> unit

setLineJoin c j sets the current line join type of canvasc to j

val getLineCap : t -> Cap.t

getLineJoin c returns the current line cap type of canvas c

val setLineCap : t -> Cap.t -> unit

setLineJoin c j sets the current line cap type of canvasc to j

val getMiterLimit : t -> float

getMiterLimit c returns the current miter limit of canvas c

val setMiterLimit : t -> float -> unit

getMiterLimit c m sets the current miter limit of canvas c to m

val getLineDashOffset : t -> float

getLineDashOffset c returns the current line offset of c

val setLineDashOffset : t -> float -> unit

setLineDashOffset c t sets the current line offset of c to t

val getLineDash : t -> float array

getLineDash c t returns the current line dash pattern of c

val setLineDash : t -> float array -> unit

setLineDash c t sets the current line dash pattern of c to t

val getStrokeColor : t -> Color.t

getStrokeColor c returns the current stroke color of canvas c

val setStrokeColor : t -> Color.t -> unit

setStrokeColor c col sets the current stroke color of canvas c to col

val setStrokeGradient : t -> Gradient.t -> unit

setStrokeGradient c grad sets the current stroke style of canvas c to the gradient grad

val setStrokePattern : t -> Pattern.t -> unit

setStrokePattern c pat sets the current stroke style of canvas c to the pattern pat

val getStrokeStyle : t -> Style.t

getStrokeStyle c returns the current stroke style of canvas c

val setStrokeStyle : t -> Style.t -> unit

setStrokeStyle c style sets the current stroke style of canvas c to style style

val getFillColor : t -> Color.t

getFillColor c returns the current fill color of canvas c

val setFillColor : t -> Color.t -> unit

setFillColor c col sets the current fill color of canvas c to col

val setFillGradient : t -> Gradient.t -> unit

setFillGradient c grad sets the current fill style of canvas c to the gradient grad

val setFillPattern : t -> Pattern.t -> unit

setFillPattern c pat sets the current fill style of canvas c to the pattern pat

val getFillStyle : t -> Style.t

getFillStyle c return the current fill style of canvas c

val setFillStyle : t -> Style.t -> unit

setFillStyle c style sets the current fill style of canvas c to style style

val getGlobalAlpha : t -> float

getGlobalAlpha c returns the current global alpha of canvas c

val setGlobalAlpha : t -> float -> unit

setGlobalAlpha c a sets the global alpha value of canvasc to a

val getGlobalCompositeOperation : t -> CompositeOp.t

getGlobalCompositeOperation c returns the global composite or blending operation of canvasc

val setGlobalCompositeOperation : t -> CompositeOp.t -> unit

setGlobalCompositeOperation c o sets the global composite or blending operation of canvasc to o

val getShadowColor : t -> Color.t

setShadowColor c returns the canvas c's shadow color

val setShadowColor : t -> Color.t -> unit

setShadowColor c col sets the canvas c's shadow color to col

val getShadowBlur : t -> float

setShadowBlur c returns the shadow blur radius of canvas c

val setShadowBlur : t -> float -> unit

setShadowBlur c b sets the shadow blur radius of canvas c to b

val getShadowOffset : t -> Vector.t

setShadowOffset c returns the offset of the shadows drawn in c

val setShadowOffset : t -> Vector.t -> unit

setShadowOffset c o sets the offset of the shadows drawn in c to o

val setFont : 
  t ->
  string ->
  size:Font.size ->
  slant:Font.slant ->
  weight:Font.weight ->
  unit

setFont c family ~size ~slant ~weight sets the current font of canvas c to the one specified by the given family, size, slant and weight

Path

val clearPath : t -> unit

clearPath c resets the path of canvas c

val closePath : t -> unit

closePath c closes the current subpath of canvas c, i.e. adds a line from the last point in the current subpath to the first point, and marks the subpath as closed. Does nothing if the subpath is empty or has a single point, or if the subpath is already closed.

val moveTo : t -> Point.t -> unit

moveTo c p starts a new subpath in canvas c containing the single point p. If the current subpath is empty, its first point is set to this point, instead of creating a new subpath. Likewise, if the current subpath has a single point, it is simply replaced by the given point.

val lineTo : t -> Point.t -> unit

lineTo c p adds the point p to the current subpath of canvas c. If the current subpath is empty, this behaves just like moveTo c ~p.

val arc : 
  t ->
  center:Point.t ->
  radius:float ->
  theta1:float ->
  theta2:float ->
  ccw:bool ->
  unit

arc c ~center ~radius ~theta1 ~theta2 ~ccw adds an arc of the given radius, centered at center, between angle theta1 to theta2 to the current subpath of canvas c. If ccw is true, the arc will be drawn counterclockwise. Note that the last point in the subpath (if such point exists) will be connected to the first point of the arc by a straight line.

val arcTo : t -> p1:Point.t -> p2:Point.t -> radius:float -> unit

arcTo c ~p1 ~p2 ~radius adds an arc of the given radius using the control points p1 and p2 to the current subpath of canvas c. If the current subpath is empty, this behaves as if moveTo c ~p:p1 was called.

val quadraticCurveTo : t -> cp:Point.t -> p:Point.t -> unit

quadraticCurveTo c ~cp ~p adds a quadratic Bezier curve using the control point cp and the end point p to the current subpath of canvas c

val bezierCurveTo : t -> cp1:Point.t -> cp2:Point.t -> p:Point.t -> unit

bezierCurve c ~cp1 ~cp2 ~p adds a cubic Bezier curve using the control points cp1 and cp2 and the end point p to the current subpath of canvas c

val rect : t -> pos:Point.t -> size:Vector.t -> unit

rect c ~pos ~size adds the rectangle specified by pos and size) to the current subpath of canvas c

val ellipse : 
  t ->
  center:Point.t ->
  radius:Vector.t ->
  rotation:float ->
  theta1:float ->
  theta2:float ->
  ccw:bool ->
  unit

ellipse c ~center ~radius ~rotation ~theta1 ~theta2 adds an ellipse with the given parameters to the current subpath of canvas c

Path stroking and filling

val fill : t -> nonzero:bool -> unit

fill c ~nonzero fills the current subpath of canvas c using the current fill color and the specified fill rule

val fillPath : t -> Path.t -> nonzero:bool -> unit

fillPath c p ~nonzero fills the path p on canvas c using the current fill style and the specified fill rule

val stroke : t -> unit

stroke c draws the outline of the current subpath of canvas c using the current stroke color and line width

val strokePath : t -> Path.t -> unit

strokePath c p draws the outline of the path p on canvas c using the current stroke style and line width

val clip : t -> nonzero:bool -> unit

clipPath c p ~nonzero intersects the current subpath of c on canvas c's clip region using the specified fill rule

val clipPath : t -> Path.t -> nonzero:bool -> unit

clipPath c p ~nonzero intersects the filled path p on canvas c's clip region using the specified fill rule

Immediate drawing

val fillRect : t -> pos:Point.t -> size:Vector.t -> unit

fillRect c ~pos ~size immediatly fills the rectangle specified by pos and size to the canvas c using the current fill color

val strokeRect : t -> pos:Point.t -> size:Vector.t -> unit

strokeRect c ~pos ~size immediatly draws the outline of the rectangle specified by pos and size to the canvas c using the current stroke color and line width

val fillText : t -> string -> Point.t -> unit

fillText c text pos immediatly draws the text text at position pos on the canvas c using the current fill color

val strokeText : t -> string -> Point.t -> unit

strokeText c text pos immediatly draws the outline of text text at position pos on the canvas c using the current stroke color and line width

val blit : 
  dst:t ->
  dpos:(int * int) ->
  src:t ->
  spos:(int * int) ->
  size:(int * int) ->
  unit

blit ~dst ~dpos ~src ~spos ~size copies the area specified by spos and size from canvas src to canvas dst at position dpos. If the given position and size yield an inconsistent area, this has no effect.

Exceptions:

Invalid_argument if either component of size is outside the range 1-32767

Direct pixel access

Warning: these functions (especially the per-pixel functions) can be slow and are not meant for updating the contents of a canvas in real-time. Better use them on offscreen canvas during loading phases.

val getPixel : t -> (int * int) -> Color.t

getPixel c pos returns the color of the pixel at position pos in canvas c. If pos is outside the canvas bounds, returns the transparent black color.

val putPixel : t -> (int * int) -> Color.t -> unit

putPixel c pos col sets the color of the pixel at position pos in canvas c to color col. If pos is outside the canvas bounds, this has no effect.

val getImageData : t -> pos:(int * int) -> size:(int * int) -> ImageData.t

getImageData c ~pos ~size returns a copy of the pixel data at position pos of size size in canvas c. Any pixel outside the canvas bounds is considered to be transparent black.

Exceptions:

Invalid_argument if either component of size is outside the range 1-32767

val putImageData : 
  t ->
  dpos:(int * int) ->
  ImageData.t ->
  spos:(int * int) ->
  size:(int * int) ->
  unit

setImageData c ~dpos id ~spos ~size overwrite the pixels at position dpos in canvas c with the provided pixel data starting at position spos and of size size. If the given position and size yield an inconsistent area, this has no effect.

Exceptions:

Invalid_argument if either component of size is outside the range 1-32767

val importPNG : t -> pos:(int * int) -> string -> t React.event

importPNG c ~pos filename loads the file filename into canvas c at position pos. The returned event will be triggered once the image is loaded.

Exceptions:

Exception.Read_png_failed if the PNG file could not be read

val exportPNG : t -> string -> unit

exportPNG c filename saves the contents of canvas c to a file with name filename

Exceptions:

Exception.Write_png_failed if the PNG file could not be written

package ocaml-canvas

Comparison and hash functions

Creation

Visibility

Rendering

Configuration

State

Transformations

Style

Path

Path stroking and filling

Immediate drawing

Direct pixel access