[m-rev.] for post-commit review: announce cairo binding

[Julien Fischer]

For post-commit review:

Branches: main

Add further documentation for the Cairo binding and announce it.

extras/graphics/mercury_cairo/README:
 	Add a instructions for building the Cairo binding, as
 	well as an overview of the C->Mercury API mapping.

extras/graphics/README:
 	Delete a remark about the Tcl/Tk and OpenGL binding
 	not be particularly complete.

 	Mention the Cairo binding.

 	Replaces references with Togl with GLUT.

extras/graphics/mercury_cairo/Cairo.options:
 	Fix some wording in a comment.

extras/README:
RELEASE_NOTES:
NEWS:
 	Announce the Cairo binding.

Julien.

Index: NEWS
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/NEWS,v
retrieving revision 1.553
diff -u -r1.553 NEWS
--- NEWS	19 Dec 2010 04:08:25 -0000	1.553
+++ NEWS	19 Dec 2010 06:16:43 -0000
@@ -101,6 +101,10 @@
  * Support for building and linking against frameworks on Mac OS X has
    been improved.

+Changes to the extras distribution:
+
+* We have added a binding to the Cairo 2D graphics library.
+

  DETAILED LISTING
  ================
Index: RELEASE_NOTES
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/RELEASE_NOTES,v
retrieving revision 1.35
diff -u -r1.35 RELEASE_NOTES
--- RELEASE_NOTES	7 Dec 2010 13:56:22 -0000	1.35
+++ RELEASE_NOTES	19 Dec 2010 06:16:43 -0000
@@ -190,7 +190,7 @@
       o  arithmetic
          -  arithmetic on complex and imaginary numbers
       o  UIs:
-        -  graphics using Tk, OpenGL/GLUT, Xlib or Allegro.
+        -  graphics using Tk, OpenGL/GLUT, Xlib, Allegro or Cairo.
          -  text interfaces using curses
          -  processing HTML forms using the CGI interface
       o  interfacing:
Index: extras/README
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/extras/README,v
retrieving revision 1.27
diff -u -r1.27 README
--- extras/README	7 Dec 2010 13:56:39 -0000	1.27
+++ extras/README	19 Dec 2010 06:16:43 -0000
@@ -33,8 +33,8 @@
  graphics	Some packages for doing graphics programming
  		and GUIs in Mercury: a Mercury interface to Tcl/Tk,
  		a Mercury binding to OpenGL, a Mercury binding to
-		GLUT, a simplified binding to Xlib and a binding
-		to Allegro/AllegroGL.
+		GLUT, a simplified binding to Xlib, a binding
+		to Allegro/AllegroGL and a Mercury binding to Cairo.

  lazy_evaluation
  		A library module `lazy' containing support for optional
@@ -42,7 +42,7 @@
  		of its use, including a module `lazy_list' that defines
  		a lazy list data type.

-lex		A lexer package for Mercury that works over the IO state,
+lex		A lexer package for Mercury that works over the I/O state,
  		strings, and so forth.  It comes with a rich set of
  		standard regular expressions and the user is free to add
  		their own. 
@@ -82,7 +82,7 @@
  		some support for Prolog-style unification constraints.

  windows_installer_generator
-		A library for generating Wix source files.  WiX is an XML
+		A library for generating WiX source files.  WiX is an XML
  		language that is used to generate Microsoft Windows Installer
  		(.msi) packages.

Index: extras/graphics/README
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/extras/graphics/README,v
retrieving revision 1.7
diff -u -r1.7 README
--- extras/graphics/README	23 Apr 2007 04:00:53 -0000	1.7
+++ extras/graphics/README	19 Dec 2010 06:16:43 -0000
@@ -1,6 +1,4 @@
  This directory contains stuff for doing graphics with Mercury.
-We have created bindings to Tcl/Tk and OpenGL. Neither are complete,
-but both are complete *enough* to be very useful.

  If you add missing functionality to any of these modules, let us know,
  and we'll see about incorporating enhancements in the main distribution.
@@ -21,15 +19,18 @@
                                  for OpenGL.

  	mercury_glut/		A Mercury binding to GLUT.
+
+        mercury_cairo/		A Mercury binding to the Cairo 2D graphics
+                                library.

  	samples/
  		calc/		A calculator that uses mercury_tcltk

  		maze/		Draws pretty mazes in 3D using OpenGL
-				and Togl.
+				and GLUT.

  		pent/		Places pentominoes on a board in 3D 
-				using OpenGL and Togl.
+				using OpenGL and GLUT.

  We haven't worked out how to prevent the Tcl/Tk library from giving a
  tcl prompt when it enters the event loop. If you know how, let us know!
Index: extras/graphics/mercury_cairo/Cairo.options
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/extras/graphics/mercury_cairo/Cairo.options,v
retrieving revision 1.1
diff -u -r1.1 Cairo.options
--- extras/graphics/mercury_cairo/Cairo.options	7 Sep 2010 15:18:35 -0000	1.1
+++ extras/graphics/mercury_cairo/Cairo.options	19 Dec 2010 06:16:43 -0000
@@ -13,7 +13,7 @@

  # What flags do we need to pass to the C compiler in order to compile
  # against cairo? 
-# Use "pkg-config --cflags cairo" to work this and substitute the result
+# Use "pkg-config --cflags cairo" to determine this and substitute the result
  # as the value of CAIRO_CFLAGS.
  #
  CAIRO_CFLAGS="-I/opt/local/include/cairo -I/opt/local/include/pixman-1 -I/opt/local/include -I/opt/local/include/freetype2 -I/opt/local/include/libpng12"
Index: extras/graphics/mercury_cairo/README
===================================================================
RCS file: extras/graphics/mercury_cairo/README
diff -N extras/graphics/mercury_cairo/README
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ extras/graphics/mercury_cairo/README	19 Dec 2010 06:16:43 -0000
@@ -0,0 +1,115 @@
+This directory contains the package `mercury_cairo' which is a Mercury binding
+to the Cairo 2D graphics library.  (See: <http://www.cairographics.org>.)
+
+
+Building the binding
+====================
+
+(1) File in the system-specific information for your system in Cairo.options.
+
+(2) Build and install with the following command:
+
+   $ mmc --make libmercury_cairo.install
+
+
+Overview of the Mercury Cairo Binding
+=====================================
+
+The remainder of this document outlines the mapping from the Cairo C API to
+Mercury.  In general, we have followed the Cairo language binding guidelines,
+<http://www.cairographics.org/manual/language-bindings.html>, where possible
+although some changes had to be made due to name clashes with other Mercury
+libraries.
+
+
+Mapping from C API types to Mercury types
+=========================================
+
+    cairo_t                       cairo.context/1.
+    cairo_pattern_t               cairo.pattern/0.
+    cairo_matrix_t                cairo.matrix/0.
+    cairo_path_t                  cairo.path/0.
+    cairo_font_options_t          cairo.font_options/0.
+    cairo_region_t                cairo.region/0.
+    cairo_scaled_font_t           cairo.scaled_font/1. 
+    cairo_content_t               cairo.content/0
+    cairo_format_t                cairo.format/0.
+    cairo_status_t                cairo.status/0.
+
+There are no types in the Mercury API that correspond directly to the C types
+cairo_surface_t and cairo_font_face_t.  In the Mercury binding these are
+represented by the type classes: cairo.surface/1 and cairo.font_face/1.
+
+
+Mapping from C functions to Mercury predicates
+==============================================
+
+In the Mercury binding, the Cairo API is split up amongst various submodules,
+each submodule providing the operations that provide a specific piece of
+functionality.  The choice has typically been governed by where a function
+appears in the Cairo API manual.
+
+The top-level module in the binding is named "cairo".  It contains
+
+  * Bindings for the major types in Cairo.
+  * Bindings for the operations on the Cairo drawing context.
+  * Bindings for error handling functionality.
+
+For example:
+
+    cairo_create()          cairo.create_context/4.
+    cairo_save()            cairo.save/3. 
+    cairo_restore()         cairo.restore/2.
+    ...
+
+Operations that create and manipulate path data are contained in the
+submodule "cairo.path".  For example:
+
+    cairo_copy_path()       cairo.path.copy_path/4.
+    cairo_copy_path_flat()  cairo.path.copy_path_flat/4.
+    cairo_append_path()     cairo.path.append_path/4.
+    ...
+
+Operations on patterns, i.e. mainly those whose C names are begin
+with cairo_pattern_, are contained in the submodule "cairo.pattern".
+For example:
+
+    cairo_pattern_add_color_stop_rgb()      cairo.pattern.add_color_stop_rgb/7
+    cairo_pattern_add_color_stop_rgba()     cairo.pattern.add_color_stop_rgba/8
+    cairo_pattern_create_rgb()              cairo.pattern.create_rgb/6
+    ...
+
+Operations on surfaces, i.e. those whose C name being with cairo_surface_,
+are contained in the submodule "cairo.surface".
+For example:
+
+    cairo_surface_finish()              cairo.surface.finish/3.
+    cairo_surface_flush()               cairo.surface.flush/3.
+    cairo_surface_get_font_options()    cairo.surface.get_font_options/4.
+    ...
+
+
+Backends Submodules
+===================
+
+The Mercury binding has submodules that provide image, PDF, PostScript, and SVG
+surfaces.  Each surface is represented by a type that is an instance of the
+cairo.surface/1 type class.  For example, the interface to image surfaces is in
+the submodule "cairo.image".
+
+Image surfaces are always supported.  PDF, PostScript, and SVG surfaces are
+optional.  The following predicates may be used to test whether they are are
+supported by an installation:
+ 
+    cairo.pdf.have_pdf_surface/0
+    cairo.ps.have_ps_surface/0
+    cairo.svg.have_svg_surface/0
+
+(The predicate cairo.png.png_is_supported/0 performs the same function for
+determining whether the PNG reading and writing capabilities in the submodule
+"cairo.png" are supported by an installation.)
+
+Other surface types, e.g. X, Quartz, Win32, are not provided by the Mercury
+Cairo binding.  The intention is that they can be provided by separate
+libraries that would provide an instance of the cairo.surface/1 type class as
+well as bindings to the required backend specific Cairo functions.

--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------