From 9f0c7bff9b3cc108455002db54fd52183bc649fd Mon Sep 17 00:00:00 2001
From: Su_Laus <[EMAIL REDACTED]>
Date: Tue, 16 May 2023 23:02:03 +0200
Subject: [PATCH] Documentation update: TIFFSetTagExtender() cannot add tags to
custom directories.
Closes #557.
---
doc/addingtags.rst | 20 +++++++++-----------
doc/functions/TIFFSetTagExtender.rst | 6 ++++++
doc/specification/coverage.rst | 2 +-
3 files changed, 16 insertions(+), 12 deletions(-)
diff --git a/doc/addingtags.rst b/doc/addingtags.rst
index c035c75d..96f35a82 100644
--- a/doc/addingtags.rst
+++ b/doc/addingtags.rst
@@ -54,7 +54,7 @@ This structure looks like this:
Generally the same as field_readcount. A few built-in exceptions exist, but
I haven't analysed why they differ.
-.. c:member:: TIFFDataType TIFFDataType.field_type
+.. c:member:: TIFFDataType TIFFFieldInfo.field_type
Type of the field. One of :c:enumerator:`TIFF_BYTE`, :c:enumerator:`TIFF_ASCII`,
:c:enumerator:`TIFF_SHORT`, :c:enumerator:`TIFF_LONG`,
@@ -63,11 +63,10 @@ This structure looks like this:
:c:enumerator:`TIFF_SLONG`, :c:enumerator:`TIFF_SRATIONAL`,
:c:enumerator:`TIFF_FLOAT`, :c:enumerator:`TIFF_DOUBLE` or
:c:enumerator:`TIFF_IFD`.
-
-.. note::
-
- Some fields can support more than one type (for
- instance short and long). These fields should have multiple TIFFFieldInfos.
+ And for BigTIFF :c:enumerator:`TIFF_LONG8`,
+ :c:enumerator:`TIFF_SLONG8` and :c:enumerator:`TIFF_IFD8`,
+ which are automatically reverted to 4 byte fields in
+ ClassicTIFF.
.. c:member:: unsigned short TIFFFieldInfo.field_bit
@@ -95,15 +94,14 @@ This structure looks like this:
A name for the tag. Normally mixed case (studly caps)
like ``StripByteCounts``, and relatively short.
-A :c:struct:`TIFFFieldInfo` definition exists for each built-in tag in the
-:file:`tif_dirinfo.c` file. Some tags which support multiple data types
-have more than one definition, one per data type supported.
+Within :file:`tif_dirinfo.c` file, the built-in TIFF tags are defined with
+:c:struct:`TIFFField` structure that has additional parameters defining the var_arg
+interface of :c:func:`TIFFSetField` and :c:func:`TIFFGetField`.
Various functions exist for getting the internal :c:struct:`TIFFFieldInfo`
definitions, including :c:func:`_TIFFFindFieldInfo`, and
:c:func:`_TIFFFindFieldInfoByName`. See
-:file:`tif_dirinfo.c` for details. There must be some mechanism to get the whole
-list, though I don't see it off hand.
+:file:`tif_dirinfo.c` for details.
.. _Tag_Auto_registration:
diff --git a/doc/functions/TIFFSetTagExtender.rst b/doc/functions/TIFFSetTagExtender.rst
index 001ec1f6..ea72cbbe 100644
--- a/doc/functions/TIFFSetTagExtender.rst
+++ b/doc/functions/TIFFSetTagExtender.rst
@@ -19,6 +19,12 @@ Description
for user defined tags as an extender callback with ``libtiff``.
A brief description can be found at :ref:`define_application_tags`.
+.. note::
+
+ :c:func:`TIFFSetTagExtender` cannot be used to extend custom directories
+ (for example EXIF, GPS or other custom directories).
+ Only the TIFF directory can be extended with additional tags.
+
See also
--------
diff --git a/doc/specification/coverage.rst b/doc/specification/coverage.rst
index 75bc7c5f..9f4bf7db 100644
--- a/doc/specification/coverage.rst
+++ b/doc/specification/coverage.rst
@@ -1466,7 +1466,7 @@ pre-multipled by Alpha. If this means nothing to you, check out
Porter & Duff's paper in the '84 SIGGRAPH proceedings: "Compositing Digital
Images".
-Tag ``RichTIFFIPTC`` (33723)is defined wrongly in TIFF/EP definition as "LONG or ASCII".
+Tag ``RichTIFFIPTC`` (33723) is defined wrongly in TIFF/EP definition as "LONG or ASCII".
``libtiff`` defines it as "UNDEFINED or BYTE".
The ``ImageDepth``