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 5.0.2
============
- COM:
  - The functions PDF_setgray*() and PDF_setrgbcolor*() are no longer
    available in the COM wrapper. These functions have been deprecated
    since PDFlib 4. Workaround: use setcolor() instead.


PDFlib 5.0.1
============
- No changes which affect compatibility.


PDFlib 5.0.0
============

- Several resource configuration mechanism are superseded by improved
  mechanisms. However, the previous configuration scheme is still supported.

- Introduced a dedicated PDFlibException class for Java. This may
  require modifications to existing catch clauses.

- The new C exception handling with PDF_TRY/PDF_CATCH makes old-style
  error handlers obsolete. However, PDF_new2() will still accept error
  handler callbacks.

- The PDF_open_pdi_callback() has been slightly modified; this affects
  only PDFlib customers who used this feature in a preliminary release.

- Changed the default value of the "inheritgstate" parameter to false.

- By default, PDFlib generates PDF 1.4 (Acrobat 5) output. This can be
  modified with

  PDF_set_parameter(p, "compatibility", "1.3");

- The following features have been removed:

  PDF_set_parameter(p, "compatibility", "1.2");

  Careful programming can still produce PDF 1.2 compatible documents,
  albeit with a PDF 1.3 header entry.

- The following functions have been removed:

  PDF_open_pdi_mem() (only implemented in custom versions of PDFlib+PDI)
  Change existing calls to the following sequence:

  PDF_create_pvf(...);
  PDF_open_pdi(...);

- C++ binding:
  Switches to new-style C++ exceptions by default (as opposed to installing
  an old-style client-supplied error handler callback function).

- PHP binding:
  Those very old API functions have been removed from the wrapper which
  stemmed from the prehistoric era before PDFlib GmbH officially supported
  the PHP wrapper. These functions have never been documented in the PDFlib
  manual, but have been kept in the PHP wrapper for compatibility reasons.
  In order to facilitate maintenance we dropped these functions.
 
  The pdf_open_memory_image() API is not affected since it actually added
  new functionality. Although PDFlib GmbH does not support this function it
  still works.

  The virtual_dir support has also been dropped. This feature is rather
  confusing since it is not supported on all platforms and configurations.
  In addition, it conflicts with the new SearchPatch facility in PDFlib.
  Finally, it didn't work when generating PDF files with PDF_open_file().


PDFlib 4.0.2 and 4.0.3
======================

- No new functions, but new features which do not affect the
  binary interface (such as support for OpenType fonts).


PDFlib 4.0.1
============

- No changes which affect compatibility.


PDFlib 4.0
==========

- The following functions have been added to the PDFlib API:

  PDF_open_pdi()
  PDF_close_pdi()
  PDF_open_pdi_page()
  PDF_close_pdi_page()
  PDF_get_pdi_parameter()
  PDF_get_pdi_value()

  PDF_begin_pattern()
  PDF_end_pattern()

  PDF_begin_template()
  PDF_end_template()

  PDF_setcolor()
  PDF_makespotcolor()

  PDF_arcn()
  PDF_add_thumbnail()

  PDF_initgraphics()
  PDF_setmatrix()

- The following functions are now deprecated (use PDF_setcolor() instead):
    PDF_setgray_fill
    PDF_setgray_stroke
    PDF_setgray
    PDF_setrgbcolor_fill
    PDF_setrgbcolor_stroke
    PDF_setrgbcolor

- PDF_endpath() has been re-implemented with slightly different semantics.

- The FontTT resource category has been removed. TrueType fonts can now be
  listed along with PostScript fonts in the FontOutline category. This
  change affects only a few customers who had access to the TrueType
  feature before PDFlib 4.0 was released.


PDFlib 3.03
===========

- This release doesn't add nor remove any function, but introduces a
  new parameter: "fontwarning"

- The deprecated function PDF_endpath() raises a non-fatal exception
  (which can be suppressed).


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

This release doesn't add nor remove any 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 has
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) { ... }
