doc: Clarify description of `FT_Stream_IoFunc`.

The existing documentation comments on `FT_Stream_IoFunc` hinted at the dual
seek/read behavior required for custom stream implementations to work, but
it didn't explicitly explain it.  Without looking at the internals of
FreeType, it was easy for someone to assume their implementation should
handle both seek and read operations all the time.  If this is done, you get
a variety of errors, but mostly just `Unknown_File_Format` (error code
0x02).

1 files changed, 9 insertions, 3 deletions

diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h
index 5f8aec7b7..acbf7041c 100644
--- a/include/freetype/ftsystem.h
+++ b/include/freetype/ftsystem.h
@@ -229,7 +229,8 @@ FT_BEGIN_HEADER
    *     A handle to the source stream.
    *
    *   offset ::
-   *     The offset of read in stream (always from start).
+   *     The offset from the start of the stream to seek to if this is a seek
+   *     operation (see note).
    *
    *   buffer ::
    *     The address of the read buffer.
@@ -241,8 +242,13 @@ FT_BEGIN_HEADER
    *   The number of bytes effectively read by the stream.
    *
    * @note:
-   *   This function might be called to perform a seek or skip operation with
-   *   a `count` of~0.  A non-zero return value then indicates an error.
+   *   This function performs a seek *or* a read operation depending on the
+   *   argument values.  If `count` is zero, the operation is a seek to
+   *   `offset` bytes.  If `count` is >~0, the operation is a read of `count`
+   *   bytes from the current position in the stream, and the `offset` value
+   *   should be ignored.
+   *
+   *   For seek operations, a non-zero return value indicates an error.
    *
    */
   typedef unsigned long