/// <summary>
/// Create a <see cref="Face"/> object from a given resource described by <see cref="OpenArgs"/>.
/// </summary>
/// <remarks><para>
/// Unlike FreeType 1.x, this function automatically creates a glyph slot for the face object which can be
/// accessed directly through <see cref="Face.Glyph"/>.
/// </para><para>
/// OpenFace can be used to quickly check whether the font format of a given font resource is supported by
/// FreeType. If the ‘faceIndex’ field is negative, the function's return value is 0 if the font format is
/// recognized, or non-zero otherwise; the function returns a more or less empty face handle in ‘*aface’ (if
/// ‘aface’ isn't NULL). The only useful field in this special case is <see cref="Face.FaceCount"/> which gives
/// the number of faces within the font file. After examination, the returned <see cref="Face"/> structure
/// should be deallocated with a call to <see cref="Face.Dispose()"/>.
/// </para><para>
/// Each new face object created with this function also owns a default <see cref="FTSize"/> object, accessible
/// as <see cref="Face.Size"/>.
/// </para><para>
/// See the discussion of reference counters in the description of FT_Reference_Face.
/// </para></remarks>
/// <param name="args">
/// A pointer to an <see cref="OpenArgs"/> structure which must be filled by the caller.
/// </param>
/// <param name="faceIndex">The index of the face within the font. The first face has index 0.</param>
/// <returns>
/// A handle to a new face object. If ‘faceIndex’ is greater than or equal to zero, it must be non-NULL.
/// </returns>
public Face OpenFace(OpenArgs args, int faceIndex)
{
if (disposed)
{
throw new ObjectDisposedException("Library", "Cannot access a disposed object.");
}
IntPtr faceRef;
Error err = FT.FT_Open_Face(Reference, args.Reference, faceIndex, out faceRef);
if (err != Error.Ok)
{
throw new FreeTypeException(err);
}
return(new Face(faceRef, this));
}
/// <summary>
/// ‘Attach’ data to a face object. Normally, this is used to read additional information for the face object.
/// For example, you can attach an AFM file that comes with a Type 1 font to get the kerning values and other
/// metrics.
/// </summary>
/// <remarks><para>
/// The meaning of the ‘attach’ (i.e., what really happens when the new file is read) is not fixed by FreeType
/// itself. It really depends on the font format (and thus the font driver).
/// </para><para>
/// Client applications are expected to know what they are doing when invoking this function. Most drivers
/// simply do not implement file attachments.
/// </para></remarks>
/// <param name="parameters">A pointer to <see cref="OpenArgs"/> which must be filled by the caller.</param>
public void AttachStream(OpenArgs parameters)
{
if (disposed)
throw new ObjectDisposedException("face", "Cannot access a disposed object.");
Error err = FT.FT_Attach_Stream(Reference, parameters.Reference);
if (err != Error.Ok)
throw new FreeTypeException(err);
}
/// <summary>
/// Create a <see cref="Face"/> object from a given resource described by <see cref="OpenArgs"/>.
/// </summary>
/// <remarks><para>
/// Unlike FreeType 1.x, this function automatically creates a glyph slot for the face object which can be
/// accessed directly through <see cref="Face.Glyph"/>.
/// </para><para>
/// OpenFace can be used to quickly check whether the font format of a given font resource is supported by
/// FreeType. If the ‘faceIndex’ field is negative, the function's return value is 0 if the font format is
/// recognized, or non-zero otherwise; the function returns a more or less empty face handle in ‘*aface’ (if
/// ‘aface’ isn't NULL). The only useful field in this special case is <see cref="Face.FaceCount"/> which gives
/// the number of faces within the font file. After examination, the returned <see cref="Face"/> structure
/// should be deallocated with a call to <see cref="Face.Dispose()"/>.
/// </para><para>
/// Each new face object created with this function also owns a default <see cref="FTSize"/> object, accessible
/// as <see cref="Face.Size"/>.
/// </para><para>
/// See the discussion of reference counters in the description of FT_Reference_Face.
/// </para></remarks>
/// <param name="args">
/// A pointer to an <see cref="OpenArgs"/> structure which must be filled by the caller.
/// </param>
/// <param name="faceIndex">The index of the face within the font. The first face has index 0.</param>
/// <returns>
/// A handle to a new face object. If ‘faceIndex’ is greater than or equal to zero, it must be non-NULL.
/// </returns>
public Face OpenFace(OpenArgs args, int faceIndex)
{
if (disposed)
throw new ObjectDisposedException("Library", "Cannot access a disposed object.");
IntPtr faceRef;
Error err = FT.FT_Open_Face(Reference, args.Reference, faceIndex, out faceRef);
if (err != Error.Ok)
throw new FreeTypeException(err);
return new Face(faceRef, this);
}
