Commit d5d048bbfe1bcfae18fa5948284c95f89d8f33a0
2022-07-03T20:26:31
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).
diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h
index 5f8aec7..acbf704 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