/****************************************************************************
*
* hvfobjs.c
*
* HVF objects manager (body).
*
* Copyright (C) 2025-2026 by
* Apple Inc.
* written by Deborah Goldsmith <goldsmit@apple.com>
*
* This file is part of the FreeType project, and may only be used,
* modified, and distributed under the terms of the FreeType project
* license, LICENSE.TXT. By continuing to use, modify, or distribute
* this file you indicate that you have read the license and
* understand and accept it fully.
*
*/
#include <freetype/internal/ftdebug.h>
#include <freetype/internal/ftstream.h>
#include <freetype/internal/sfnt.h>
#include <freetype/tttags.h>
#include <freetype/ftmm.h>
#include "hvfobjs.h"
#include "hvferror.h"
/**************************************************************************
*
* The macro FT_COMPONENT is used in trace mode. It is an implicit
* parameter of the FT_TRACE() and FT_ERROR() macros, used to print/log
* messages during execution.
*/
#undef FT_COMPONENT
#define FT_COMPONENT hvfobjs
#ifdef FT_CONFIG_OPTION_HVF
/**************************************************************************
*
* FACE MANAGEMENT
*
*/
static FT_Error
hvf_load_tables( HVF_Face face )
{
FT_Error error;
FT_Stream stream;
TT_Face tt_face = (TT_Face)face; /* Cast to access TT_Face members. */
/* Use the stream from TT_Face root. */
stream = FT_FACE_STREAM( face );
/* Load required 'hvgl' table using memory mapping. */
error = tt_face->goto_table( tt_face, TTAG_hvgl,
stream, &face->hvgl_size );
if ( error )
{
FT_TRACE2(( "hvf_load_tables: missing required 'hvgl' table\n" ));
return error;
}
/* Memory-map the 'hvgl' table data instead of copying it. */
if ( FT_FRAME_EXTRACT( face->hvgl_size, face->hvgl_data ) )
{
face->hvgl_size = 0;
FT_TRACE2(( "hvf_load_tables: failed to extract 'hvgl' table\n" ));
return FT_THROW( Invalid_Table );
}
FT_TRACE2(( "hvf_load_tables: memory-mapped 'hvgl' table (%lu bytes)\n",
face->hvgl_size ));
/* Load optional 'hvpm' table using memory mapping. */
error = tt_face->goto_table( tt_face, TTAG_hvpm,
stream, &face->hvpm_size );
if ( error )
{
face->hvpm_data = NULL; /* Ensure NULL for pointer check. */
face->hvpm_size = 0;
FT_TRACE2(( "hvf_load_tables: no 'hvpm' table found (optional)\n" ));
}
else
{
/* Memory-map the 'hvpm' table data instead of copying it. */
if ( FT_FRAME_EXTRACT( face->hvpm_size, face->hvpm_data ) )
{
face->hvpm_data = NULL;
face->hvpm_size = 0;
FT_TRACE2(( "hvf_load_tables: failed to extract 'hvpm' table\n" ));
}
#ifdef FT_DEBUG_LEVEL_TRACE
else
FT_TRACE2(( "hvf_load_tables:"
" memory-mapped 'hvpm' table (%lu bytes)\n",
face->hvpm_size ));
#endif
}
return FT_Err_Ok;
}
static FT_Error
hvf_init_renderer( HVF_Face face )
{
FT_Error error = FT_Err_Ok;
FT_Memory memory = FT_FACE_MEMORY( face );
size_t storage_size;
if ( !face->hvgl_data )
return FT_THROW( Invalid_Table );
/* Create HVF renderer - only once per face. */
if ( !face->renderer )
{
if ( HVF_IS_AVAILABLE )
{
int hvf_result;
/* Get required storage size. */
storage_size = HVF_part_renderer_storage_size();
if ( storage_size == 0 )
{
FT_TRACE1(( "hvf_init_renderer:"
" HVF_part_renderer_storage_size failed\n" ));
return FT_THROW( Invalid_Table );
}
/* Allocate storage for renderer. */
if ( FT_ALLOC( face->renderer, storage_size ) )
return error;
/* Initialize HVF renderer with 'hvgl' and optional 'hvpm' */
/* table data. */
hvf_result =
HVF_open_part_renderer( face->hvgl_data,
face->hvgl_size,
face->hvpm_data, /* NULL if missing */
face->hvpm_size, /* 0 if missing */
face->renderer,
storage_size );
if ( hvf_result != 0 )
{
FT_TRACE1(( "hvf_init_renderer:"
" HVF_open_part_renderer failed (error %d)\n",
hvf_result ));
FT_FREE( face->renderer );
return FT_THROW( Invalid_Table );
}
face->cache_count = 0;
FT_TRACE2(( "hvf_init_renderer:"
" HVF renderer initialized (%s hvpm)\n",
face->hvpm_data ? "with" : "without" ));
}
else
{
FT_TRACE3(( "hvf_init_renderer: HVF not available at runtime\n" ));
return FT_THROW( Invalid_Table );
}
}
return error;
}
static FT_Error
hvf_init_axis_coordinates( HVF_Face face )
{
FT_Error error = FT_Err_Ok;
FT_Memory memory = FT_FACE_MEMORY( face );
FT_MM_Var* mm_var = NULL;
/* Initialize axis data. */
face->num_axes = 0;
face->axis_coords = NULL;
/* Check whether this is a variable font and get axis information. */
error = FT_Get_MM_Var( (FT_Face)face, &mm_var );
if ( error )
{
/* Not a variable font or error getting variation info - */
/* that's fine. */
FT_TRACE3(( "hvf_init_axis_coordinates:"
" not a variable font or no MM info (error %x)\n",
error ));
return FT_Err_Ok;
}
if ( mm_var && mm_var->num_axis > 0 )
{
face->num_axes = mm_var->num_axis;
/* Allocate storage for HVF axis coordinates. */
if ( FT_QNEW_ARRAY( *(HVFAxisValue**)&face->axis_coords,
face->num_axes ) )
{
face->num_axes = 0;
goto Cleanup;
}
/* Initialize coordinates using the shared refresh function. */
error = hvf_refresh_axis_coordinates( face );
if ( error )
{
FT_FREE( face->axis_coords );
face->num_axes = 0;
goto Cleanup;
}
}
Cleanup:
if ( mm_var )
FT_Done_MM_Var( FT_FACE_LIBRARY( face ), mm_var );
return error;
}
FT_LOCAL_DEF( FT_Error )
hvf_refresh_axis_coordinates( HVF_Face face )
{
FT_Error error = FT_Err_Ok;
FT_Memory memory = FT_FACE_MEMORY( face );
FT_Fixed* ft_coords = NULL;
FT_UInt i;
/* Only refresh if we have cached coordinates. */
if ( !face->axis_coords || face->num_axes == 0 )
return FT_Err_Ok;
/* Allocate temporary storage for current FreeType coordinates. */
if ( FT_QNEW_ARRAY( ft_coords, face->num_axes ) )
return error;
/* Get current variation coordinates. */
error = FT_Get_Var_Blend_Coordinates( (FT_Face)face,
face->num_axes, ft_coords );
if ( error )
{
/* If we can't get coordinates, set to defaults. */
FT_ARRAY_ZERO( (HVFAxisValue*)face->axis_coords, face->num_axes );
FT_TRACE3(( "hvf_refresh_axis_coordinates:"
" could not get blend coordinates, using defaults\n" ));
error = FT_Err_Ok; /* Not fatal. */
}
else
{
/* Convert FreeType coordinates to HVF coordinates. */
for ( i = 0; i < face->num_axes; i++ )
{
((HVFAxisValue*)face->axis_coords)[i] =
FT_COORD_TO_HVF_AXIS( ft_coords[i] );
FT_TRACE5(( "hvf_refresh_axis_coordinates:"
" axis %u: FT coord %ld -> HVF coord %f\n",
i, ft_coords[i],
((HVFAxisValue*)face->axis_coords)[i] ));
}
FT_TRACE3(( "hvf_refresh_axis_coordinates:"
" refreshed %u axis coordinates\n", face->num_axes ));
/* Clear HVF renderer cache since axis coordinates changed. */
/* Cached parts were rendered with old axis values and are */
/* now invalid. */
if ( face->renderer )
{
if ( HVF_IS_AVAILABLE )
{
HVF_clear_part_cache( (HVFPartRenderer*)face->renderer );
face->cache_count = 0;
FT_TRACE4(( "hvf_refresh_axis_coordinates:"
" cleared HVF cache due to axis change\n" ));
}
#ifdef FT_DEBUG_LEVEL_TRACE
else
FT_TRACE3(( "hvf_refresh_axis_coordinates:"
" HVF not available at runtime\n" ));
#endif
}
}
/* Free temporary FreeType coordinate storage. */
FT_FREE( ft_coords );
return error;
}
/**************************************************************************
*
* @Function:
* hvf_face_init
*
* @Description:
* Initialize a given HVF face object.
*
* @Input:
* stream ::
* The source font stream.
*
* face_index ::
* The index of the font face in the resource.
*
* num_params ::
* Number of additional generic parameters. Ignored.
*
* params ::
* Additional generic parameters. Ignored.
*
* @InOut:
* face ::
* The newly built face object.
*
* @Return:
* FreeType error code. 0 means success.
*/
FT_LOCAL_DEF( FT_Error )
hvf_face_init( FT_Stream stream,
FT_Face face,
FT_Int typeface_index,
FT_Int num_params,
FT_Parameter* parameters )
{
FT_Error error;
FT_Library library = FT_FACE_LIBRARY( face );
SFNT_Service sfnt;
TT_Face tt_face = (TT_Face)face; /* Cast to access TT_Face members. */
FT_TRACE2(( "HVF driver\n" ));
/* Check HVF availability at runtime (Apple platforms only). */
if ( HVF_IS_AVAILABLE )
; /* `HVF_IS_AVAILABLE` must not be negated for strange reasons. */
else
{
FT_TRACE2(( "hvf_face_init: HVF not available at runtime\n" ));
return FT_THROW( Unknown_File_Format );
}
/* Check for SFNT wrapper. */
sfnt = (SFNT_Service)FT_Get_Module_Interface( library, "sfnt" );
if ( !sfnt )
{
FT_ERROR(( "hvf_face_init: cannot access 'sfnt' module\n" ));
error = FT_THROW( Missing_Module );
goto Exit;
}
/* Create input stream from resource. */
if ( FT_STREAM_SEEK( 0 ) )
goto Exit;
FT_TRACE2(( " " ));
/* Check that we have a valid HVF font. */
error = sfnt->init_face( stream, tt_face, typeface_index,
num_params, parameters );
if ( error )
{
FT_TRACE1(( "hvf_face_init: sfnt initialization failed (%d)\n",
error ));
goto Exit;
}
/* Verify this is actually an HVF font by checking for 'hvgl' table. */
error = tt_face->goto_table( tt_face, TTAG_hvgl, stream, NULL );
if ( error )
{
FT_TRACE1(( "hvf_face_init:"
" not an HVF font (missing 'hvgl' table)\n" ));
error = FT_THROW( Unknown_File_Format );
goto Exit;
}
/* Mark face as scalable. */
face->face_flags |= FT_FACE_FLAG_SCALABLE;
/* If we are performing a simple font format check, exit immediately. */
if ( typeface_index < 0 )
return FT_Err_Ok;
/* Load font directory. */
error = sfnt->load_face( stream, tt_face, typeface_index,
num_params, parameters );
if ( error )
goto Exit;
/* Load HVF-specific tables. */
error = hvf_load_tables( (HVF_Face)face );
if ( error )
goto Exit;
/* Initialize HVF renderer. */
error = hvf_init_renderer( (HVF_Face)face );
if ( error )
goto Exit;
/* Get variation axis information once during face initialization. */
error = hvf_init_axis_coordinates( (HVF_Face)face );
if ( error )
goto Exit;
FT_TRACE2(( "hvf_face_init: HVF face initialized successfully\n" ));
Exit:
return error;
}
/**************************************************************************
*
* @Function:
* hvf_face_done
*
* @Description:
* Finalize a given face object.
*
* @Input:
* face ::
* A pointer to the face object to destroy.
*/
FT_LOCAL_DEF( void )
hvf_face_done( FT_Face face )
{
FT_Memory memory;
FT_Stream stream;
TT_Face tt_face;
HVF_Face hvf_face;
SFNT_Service sfnt;
if ( !face )
return;
memory = FT_FACE_MEMORY( face );
stream = FT_FACE_STREAM( face );
hvf_face = (HVF_Face)face;
tt_face = (TT_Face)face;
/* Use inherited SFNT service pointer */
sfnt = (SFNT_Service)tt_face->sfnt;
/* Clean up HVF renderer. */
if ( hvf_face->renderer )
{
if ( HVF_IS_AVAILABLE )
HVF_close_part_renderer( (HVFPartRenderer*)hvf_face->renderer );
#ifdef FT_DEBUG_LEVEL_TRACE
else
FT_TRACE3(( "hvf_face_done: HVF not available at runtime\n" ));
#endif
FT_FREE( hvf_face->renderer );
}
/* Release axis coordinates storage. */
if ( hvf_face->axis_coords )
FT_FREE( hvf_face->axis_coords );
/* Release memory-mapped table data. */
if ( hvf_face->hvgl_data )
FT_FRAME_RELEASE( hvf_face->hvgl_data );
if ( hvf_face->hvpm_data )
FT_FRAME_RELEASE( hvf_face->hvpm_data );
/* Clean up SFNT (this will clean up the TT_Face base class). */
if ( sfnt )
sfnt->done_face( tt_face );
}
#else /* !FT_CONFIG_OPTION_HVF */
FT_LOCAL_DEF( FT_Error )
hvf_face_init( FT_Stream stream,
FT_Face face,
FT_Int typeface_index,
FT_Int num_params,
FT_Parameter* parameters )
{
FT_UNUSED( stream );
FT_UNUSED( face );
FT_UNUSED( typeface_index );
FT_UNUSED( num_params );
FT_UNUSED( parameters );
return FT_THROW( Unknown_File_Format );
}
#endif /* !FT_CONFIG_OPTION_HVF */
/* END */
|
