API changes
===========

This file documents those API changes which affect
existing PDFlib client programs. Although we go to
some efforts in maintaining the existing API functions,
it is sometimes necessary to incorporate a few non-backward
compatible changes in order to streamline the API and
incorporate new or extended functions.


PDFlib 3.02
===========

This release doesn't add nor remove function. However, since PDFlib 3.01
removed some obsolete and undocumented functions, 3.02 can be considered
incompatible to 3.0. For this reason, the libtool version number have
been increased such that PDFlib 3.02 is not binary compatible, although
for users of the documented PDFlib 3.0 API it is completely backward
compatible.


Changes in PDFlib 3.01
======================

This is a maintenance release which is binary compatible with 3.0.
However, a few bug fixes may result in different behaviour when
compared to 3.0. These are not incompatibilities, rather 3.0 behaved
in the wrong way which is now fixed. See the change log for details.

- The following functions, which were no longer supported nor documented in
  PDFlib 3.0 (but were still available), have been removed from all language
  bindings which still included them. Use the appropriate substitute functions
  as outlined below:

  PDF_open_TIFF		use PDF_open_image_file(p, "tiff", filename, "", 0) instead
  PDF_open_JPEG		use PDF_open_image_file(p, "jpeg", filename, "", 0) instead
  PDF_open_GIF		use PDF_open_image_file(p, "gif", filename, "", 0) instead

  PDF_get_font		use PDF_get_value(p, "font", 0) instead
  PDF_get_fontsize	use PDF_get_value(p, "fontsize", 0) instead
  PDF_get_fontname	use PDF_get_parameter(p, "fontname", 0) instead
  PDF_get_image_height	use PDF_get_value(p, "imageheight", image) instead
  PDF_get_image_width	use PDF_get_value(p, "imagewidth", image) instead

  PDF_set_fillrule	use PDF_set_parameter(p, "fillrule", fillrule) instead
  PDF_set_leading	use PDF_set_value(p, "leading", leading) instead
  PDF_set_text_rise	use PDF_set_value(p, "textrise", rise) instead
  PDF_set_horiz_scaling	use PDF_set_value(p, "horizscaling", scale) instead
  PDF_set_text_rendering use PDF_set_value(p, "textrendering", mode) instead
  PDF_set_char_spacing	use PDF_set_value(p, "charspacing", spacing) instead
  PDF_set_word_spacing	use PDF_set_value(p, "wordspacing", spacing) instead
  PDF_set_duration	use PDF_set_value(p, "duration", t) instead
  PDF_set_transition	use PDF_set_value(p, "duration", t) instead


API changes for PDFlib 3.0
==========================

- PDF_set_text_matrix() is no longer supported. Use PDF_scale(),
  PDF_translate(), PDF_rotate(), and PDF_skew() instead, or PDF_concat()
  if you actually have to deal with matrices.

- PDF_findfont() no longer returns -1 on error, but raises an exception
  which seems more appropriate to font misconfigurations (or spelling
  errors in the font or encoding names). Although existing code need
  not necessarily be changed (assuming an error handler is already in
  place), the following change is suggested:
  Change
    font = PDF_findfont(p, fontname, encoding, embed);
    if (font == -1) {
	...
    }

    -- to --

    font = PDF_findfont(p, fontname, encoding, embed);

- The name of the pseudo encoding for the platform character set changed:
  Change
    PDF_findfont(p, fontname, "default", embed);
    -- to --
    PDF_findfont(p, fontname, "host", embed);

- The image functions have been consolidated into a single API function; use
  PDF_open_image_file() instead of PDF_open_*():
  Change
    PDF_open_GIF(p, filename)
    -- to --
    PDF_open_image_file(p, "gif", filename, "", 0)

    PDF_open_TIFF(p, filename)
    -- to --
    PDF_open_image_file(p, "tiff", filename, "", 0)

    PDF_open_JPEG(p, filename)
    -- to --
    PDF_open_image_file(p, "jpeg", filename, "", 0)

  The old image functions are still available, though.


Java binding:

- In the course of reworking the Java API all functions marked as obsolete
  in the manual have been removed. Use the appropriate substitutes instead:

  open_TIFF
  open_JPEG
  open_GIF

  get_font
  get_fontsize
  get_fontname
  get_image_height
  get_image_width

  set_fillrule
  set_leading
  set_text_rise
  set_horiz_scaling
  set_text_rendering
  set_char_spacing
  set_word_spacing
  set_duration
  set_transition

- Implements package support. Add the following line at the beginning of
  all PDFlib client programs:

  import com.PDFlib.pdflib;

- Switch to an object-oriented approach, and dropped the PDF_ prefix
  from all method names: Change

  long p;
  int font;
  p = pdflib.PDF_new();
  if (pdflib.PDF_open_file(p, "hello_java.pdf") == -1) {

  -- to --

  pdflib p;
  p = new pdflib();
  if (p.open_file("hello_java.pdf") == -1) {

- PDF_boot() and PDF_shutdown are no longer available, but shouldn't
  have been used anyway.


Perl binding:

- The name of the shared library changed, requiring a small change in scripts:
  Change
    use pdflib 2.10
    -- to --
    use pdflib_pl 2.10

- "package pdflib" is no longer necessary at the beginning of the Perl script.

- PDF_boot() and PDF_shutdown are no longer available, but shouldn't
  have been used anyway.


Python binding:

- The name of the shared library changed, requiring a small change in scripts:
  Change
    from pdflib import *
    -- to --
    from pdflib_py import *

- PDF_boot() and PDF_shutdown are no longer available, but shouldn't
  have been used anyway.


Tcl binding:

- PDF_boot() and PDF_shutdown are no longer available, but shouldn't
  have been used anyway.


Visual Basic binding:

- There is no longer a dedicated VB binding; it is replaced by the
  much more versatile ActiveX binding. This requires VB clients to
  adapt their syntax to the ActiveX component.


API changes in PDFlib V2.01
===========================
- PDF_place_inline_image() is no longer supported; use PDF_place_image()
  instead (same interface):
  Change
    PDF_place_inline_image()
    -- to --
    PDF_place_image()

- PDF_put_image() is no longer required. Instead, the image data is
  "parked" immediately on PDF_open_*():
  Delete
    PDF_put_image()

- PDF_execute_image() is no longer required. Instead, PDF_place_image()
  can be called multiple times for a given PDF:
  Change
    PDF_execute_image()
    -- to --
    PDF_place_image()

- The interface and functionality of PDF_open_memory_image() changed:
  Change
    int PDF_open_memory_image(PDF *p, unsigned char *buffer,
		int width, int height, int components, int bpc);
    -- to --
    int PDF_open_image(PDF *p, "raw", "memory", const char *data, long len,
		int width, int height, int components, int bpc, NULL);


API changes in PDFlib V2.0
==========================

- All API functions with parameters of type "char *" changed to "const char *".

- change
    PDF_data_source_from_buf()
    -- to --
    int PDF_open_memory_image(PDF *p, unsigned char *buffer,
    	int width, int height, int components, int bpc)
- change
    PDF_set_text_matrix(PDF *p, PDF_matrix m);
    -- to --
    void PDF_set_text_matrix(PDF *p,
    	float a, float b, float c, float d, float e, float f);

- change
    PDF_add_outline(p, text);
    -- to --
    PDF_add_bookmark(p, text, -1, 0);

- change
    PDF_info *PDF_get_info(void);
    -- to --
    PDF_set_info(PDF *p, char *key, char *value);
    (after PDF_new() and PDF_open_*())

- change
    PDF_image->width and PDF_image->height
    -- to --
    PDF_get_image_width(PDF *p, PDF_image *image)
    -- and --
    PDF_get_image_height(PDF *p, PDF_image *image);

- change
    PDF_info->error_handler = handler;
    -- to --
    PDF_new2(handler, ...);
    Watch out for the changed signature of the error handler.

- change
    void PDF_data_source_from_buf(*p, *src, buffer, len);
    -- to --
    PDF_image *PDF_open_memory_image(p, buffer, width, height, components, bpc);
    void PDF_close_image(p, image);

- change
    a4.width to a4_width etc.

- change
    PDF_image image; /* for PDF_open_[GIF|JPEG|TIFF|memory_image] */
    -- to --
    int image;

- change
    PDF_close_[GIF|JPEG|TIFF|memory_image];
    -- to --
    PDF_close_image();

- change
    PDF_transition(p, type);
    -- to --
    PDF_transition(p, "type");

- change
    PDF_set_font(p, fontname, size, encoding);
    -- to  --
    int PDF_findfont(p, fontname, encoding, embed);
    if (font == -1)
	/* handle unavailable font */
    PDF_setfont(p, font, size);

    Note: the old PDF_set_font() is still available for compatibility.

- change
    PDF_stringwidth(char *text);
    -- to --
    PDF_stringwidth(text, PDF_get_font(p), PDF_get_fontsize(p));

- change
    PDF_open(filename);
    -- to --
    p = PDF_new();
    if (PDF_open_file(filename) == -1) { ... }
    -- or --
    p = PDF_new();
    if (PDF_open_fp(fp) == -1) { ... }
