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).
This commit is contained in:
Stephen Holdaway 2022-07-03 20:26:31 +12:00 committed by Werner Lemberg
parent 31b14fd4dc
commit d5d048bbfe
1 changed files with 9 additions and 3 deletions

View File

@ -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