*
*
* | Value |
* Name |
* Android Definition |
*
*
*
*
* | 100 |
* Thin |
* {@link FontStyle#FONT_WEIGHT_THIN} |
*
*
* | 200 |
* Extra Light (Ultra Light) |
* {@link FontStyle#FONT_WEIGHT_EXTRA_LIGHT} |
*
*
* | 300 |
* Light |
* {@link FontStyle#FONT_WEIGHT_LIGHT} |
*
*
* | 400 |
* Normal (Regular) |
* {@link FontStyle#FONT_WEIGHT_NORMAL} |
*
*
* | 500 |
* Medium |
* {@link FontStyle#FONT_WEIGHT_MEDIUM} |
*
*
* | 600 |
* Semi Bold (Demi Bold) |
* {@link FontStyle#FONT_WEIGHT_SEMI_BOLD} |
*
*
* | 700 |
* Bold |
* {@link FontStyle#FONT_WEIGHT_BOLD} |
*
*
* | 800 |
* Extra Bold (Ultra Bold) |
* {@link FontStyle#FONT_WEIGHT_EXTRA_BOLD} |
*
*
* | 900 |
* Black (Heavy) |
* {@link FontStyle#FONT_WEIGHT_BLACK} |
*
*
*
*
* @see FontStyle#FONT_WEIGHT_THIN
* @see FontStyle#FONT_WEIGHT_EXTRA_LIGHT
* @see FontStyle#FONT_WEIGHT_LIGHT
* @see FontStyle#FONT_WEIGHT_NORMAL
* @see FontStyle#FONT_WEIGHT_MEDIUM
* @see FontStyle#FONT_WEIGHT_SEMI_BOLD
* @see FontStyle#FONT_WEIGHT_BOLD
* @see FontStyle#FONT_WEIGHT_EXTRA_BOLD
* @see FontStyle#FONT_WEIGHT_BLACK
* @param weight a weight value
* @return this builder
*/
public @NonNull Builder setWeight(
@IntRange(from = FontStyle.FONT_WEIGHT_MIN, to = FontStyle.FONT_WEIGHT_MAX)
int weight) {
Preconditions.checkArgument(
FontStyle.FONT_WEIGHT_MIN <= weight && weight <= FontStyle.FONT_WEIGHT_MAX);
mWeight = weight;
return this;
}
/**
* Sets italic information of the font.
*
* Tells the system the style of the given font. If this function is not called, the system
* will resolve the style by reading font tables.
*
* For example, if you want to use italic font as upright font, call {@code
* setSlant(FontStyle.FONT_SLANT_UPRIGHT)} explicitly.
*
* @return this builder
*/
public @NonNull Builder setSlant(@FontStyle.FontSlant int slant) {
mItalic = slant == FontStyle.FONT_SLANT_UPRIGHT ? STYLE_NORMAL : STYLE_ITALIC;
return this;
}
/**
* Sets an index of the font collection. See {@link android.R.attr#ttcIndex}.
*
* @param ttcIndex An index of the font collection. If the font source is not font
* collection, do not call this method or specify 0.
* @return this builder
*/
public @NonNull Builder setTtcIndex(@IntRange(from = 0) int ttcIndex) {
mTtcIndex = ttcIndex;
return this;
}
/**
* Sets the font variation settings.
*
* @param variationSettings see {@link FontVariationAxis#fromFontVariationSettings(String)}
* @return this builder
* @throws IllegalArgumentException If given string is not a valid font variation settings
* format.
*/
public @NonNull Builder setFontVariationSettings(@Nullable String variationSettings) {
mAxes = FontVariationAxis.fromFontVariationSettings(variationSettings);
return this;
}
/**
* Sets the font variation settings.
*
* @param axes an array of font variation axis tag-value pairs
* @return this builder
*/
public @NonNull Builder setFontVariationSettings(@Nullable FontVariationAxis[] axes) {
mAxes = axes == null ? null : axes.clone();
return this;
}
/**
* Creates the font based on the configured values.
* @return the Font object
*/
public @NonNull Font build() throws IOException {
if (mException != null) {
throw new IOException("Failed to read font contents", mException);
}
if (mWeight == NOT_SPECIFIED || mItalic == NOT_SPECIFIED) {
final int packed = FontFileUtil.analyzeStyle(mBuffer, mTtcIndex, mAxes);
if (FontFileUtil.isSuccess(packed)) {
if (mWeight == NOT_SPECIFIED) {
mWeight = FontFileUtil.unpackWeight(packed);
}
if (mItalic == NOT_SPECIFIED) {
mItalic = FontFileUtil.unpackItalic(packed) ? STYLE_ITALIC : STYLE_NORMAL;
}
} else {
mWeight = 400;
mItalic = STYLE_NORMAL;
}
}
mWeight = Math.max(FontStyle.FONT_WEIGHT_MIN,
Math.min(FontStyle.FONT_WEIGHT_MAX, mWeight));
final boolean italic = (mItalic == STYLE_ITALIC);
final int slant = (mItalic == STYLE_ITALIC)
? FontStyle.FONT_SLANT_ITALIC : FontStyle.FONT_SLANT_UPRIGHT;
final long builderPtr = nInitBuilder();
if (mAxes != null) {
for (FontVariationAxis axis : mAxes) {
nAddAxis(builderPtr, axis.getOpenTypeTagValue(), axis.getStyleValue());
}
}
final ByteBuffer readonlyBuffer = mBuffer.asReadOnlyBuffer();
final String filePath = mFile == null ? "" : mFile.getAbsolutePath();
long ptr;
final Font font;
if (mFont == null) {
ptr = nBuild(builderPtr, readonlyBuffer, filePath, mLocaleList, mWeight, italic,
mTtcIndex);
font = new Font(ptr);
} else {
ptr = nClone(mFont.getNativePtr(), builderPtr, mWeight, italic, mTtcIndex);
font = new Font(ptr);
}
return font;
}
/**
* Native methods for creating Font
*/
private static native long nInitBuilder();
@CriticalNative
private static native void nAddAxis(long builderPtr, int tag, float value);
private static native long nBuild(
long builderPtr, @NonNull ByteBuffer buffer, @NonNull String filePath,
@NonNull String localeList, int weight, boolean italic, int ttcIndex);
@FastNative
private static native long nClone(long fontPtr, long builderPtr, int weight,
boolean italic, int ttcIndex);
}
private final long mNativePtr; // address of the shared ptr of minikin::Font
private final Object mLock = new Object();
@GuardedBy("mLock")
private @NonNull ByteBuffer mBuffer = null;
@GuardedBy("mLock")
private boolean mIsFileInitialized = false;
@GuardedBy("mLock")
private @Nullable File mFile = null;
@GuardedBy("mLock")
private FontStyle mFontStyle = null;
@GuardedBy("mLock")
private @Nullable FontVariationAxis[] mAxes = null;
@GuardedBy("mLock")
private @NonNull LocaleList mLocaleList = null;
/**
* Use Builder instead
*
* Caller must increment underlying minikin::Font ref count.
* This class takes the ownership of the passing native objects.
*
* @hide
*/
public Font(long nativePtr) {
mNativePtr = nativePtr;
NoImagePreloadHolder.FONT_REGISTRY.registerNativeAllocation(this, mNativePtr);
}
/**
* Returns a font file buffer.
*
* Duplicate before reading values by {@link ByteBuffer#duplicate()} for avoiding unexpected
* reading position sharing.
*
* @return a font buffer
*/
public @NonNull ByteBuffer getBuffer() {
synchronized (mLock) {
if (mBuffer == null) {
// Create new instance of native FontWrapper, i.e. incrementing ref count of
// minikin Font instance for keeping buffer fo ByteBuffer reference which may live
// longer than this object.
long ref = nCloneFont(mNativePtr);
ByteBuffer fromNative = nNewByteBuffer(mNativePtr);
// Bind ByteBuffer's lifecycle with underlying font object.
NoImagePreloadHolder.BUFFER_REGISTRY.registerNativeAllocation(fromNative, ref);
// JNI NewDirectBuffer creates writable ByteBuffer even if it is mmaped readonly.
mBuffer = fromNative.asReadOnlyBuffer();
}
return mBuffer;
}
}
/**
* Returns a file path of this font.
*
* This returns null if this font is not created from regular file.
*
* @return a file path of the font
*/
public @Nullable File getFile() {
synchronized (mLock) {
if (!mIsFileInitialized) {
String path = nGetFontPath(mNativePtr);
if (!TextUtils.isEmpty(path)) {
mFile = new File(path);
}
mIsFileInitialized = true;
}
return mFile;
}
}
/**
* Get a style associated with this font.
*
* @see Builder#setWeight(int)
* @see Builder#setSlant(int)
* @return a font style
*/
public @NonNull FontStyle getStyle() {
synchronized (mLock) {
if (mFontStyle == null) {
int packedStyle = nGetPackedStyle(mNativePtr);
mFontStyle = new FontStyle(
FontFileUtil.unpackWeight(packedStyle),
FontFileUtil.unpackItalic(packedStyle)
? FontStyle.FONT_SLANT_ITALIC : FontStyle.FONT_SLANT_UPRIGHT);
}
return mFontStyle;
}
}
/**
* Get a TTC index value associated with this font.
*
* If TTF/OTF file is provided, this value is always 0.
*
* @see Builder#setTtcIndex(int)
* @return a TTC index value
*/
public @IntRange(from = 0) int getTtcIndex() {
return nGetIndex(mNativePtr);
}
/**
* Get a font variation settings associated with this font
*
* @see Builder#setFontVariationSettings(String)
* @see Builder#setFontVariationSettings(FontVariationAxis[])
* @return font variation settings
*/
public @Nullable FontVariationAxis[] getAxes() {
synchronized (mLock) {
if (mAxes == null) {
int axisCount = nGetAxisCount(mNativePtr);
mAxes = new FontVariationAxis[axisCount];
char[] charBuffer = new char[4];
for (int i = 0; i < axisCount; ++i) {
long packedAxis = nGetAxisInfo(mNativePtr, i);
float value = Float.intBitsToFloat((int) (packedAxis & 0x0000_0000_FFFF_FFFFL));
charBuffer[0] = (char) ((packedAxis & 0xFF00_0000_0000_0000L) >>> 56);
charBuffer[1] = (char) ((packedAxis & 0x00FF_0000_0000_0000L) >>> 48);
charBuffer[2] = (char) ((packedAxis & 0x0000_FF00_0000_0000L) >>> 40);
charBuffer[3] = (char) ((packedAxis & 0x0000_00FF_0000_0000L) >>> 32);
mAxes[i] = new FontVariationAxis(new String(charBuffer), value);
}
}
}
return mAxes;
}
/**
* Get a locale list of this font.
*
* This is always empty if this font is not a system font.
* @return a locale list
*/
public @NonNull LocaleList getLocaleList() {
synchronized (mLock) {
if (mLocaleList == null) {
String langTags = nGetLocaleList(mNativePtr);
if (TextUtils.isEmpty(langTags)) {
mLocaleList = LocaleList.getEmptyLocaleList();
} else {
mLocaleList = LocaleList.forLanguageTags(langTags);
}
}
return mLocaleList;
}
}
/**
* Retrieve the glyph horizontal advance and bounding box.
*
* Note that {@link android.graphics.Typeface} in {@link android.graphics.Paint} is ignored.
*
* @param glyphId a glyph ID
* @param paint a paint object used for resolving glyph style
* @param outBoundingBox a nullable destination object. If null is passed, this function just
* return the horizontal advance. If non-null is passed, this function
* fills bounding box information to this object.
* @return the amount of horizontal advance in pixels
*/
public float getGlyphBounds(@IntRange(from = 0) int glyphId, @NonNull Paint paint,
@Nullable RectF outBoundingBox) {
return nGetGlyphBounds(mNativePtr, glyphId, paint.getNativeInstance(), outBoundingBox);
}
/**
* Retrieve the font metrics information.
*
* Note that {@link android.graphics.Typeface} in {@link android.graphics.Paint} is ignored.
*
* @param paint a paint object used for retrieving font metrics.
* @param outMetrics a nullable destination object. If null is passed, this function only
* retrieve recommended interline spacing. If non-null is passed, this function
* fills to font metrics to it.
*
* @see Paint#getFontMetrics()
* @see Paint#getFontMetricsInt()
*/
public void getMetrics(@NonNull Paint paint, @Nullable Paint.FontMetrics outMetrics) {
nGetFontMetrics(mNativePtr, paint.getNativeInstance(), outMetrics);
}
/** @hide */
public long getNativePtr() {
return mNativePtr;
}
/**
* Returns the unique ID of the source font data.
*
* You can use this identifier as a key of the cache or checking if two fonts can be
* interpolated with font variation settings.
*
*
* // Following three Fonts, fontA, fontB, fontC have the same identifier.
* Font fontA = new Font.Builder("/path/to/font").build();
* Font fontB = new Font.Builder(fontA).setTtcIndex(1).build();
* Font fontC = new Font.Builder(fontB).setFontVariationSettings("'wght' 700).build();
*
* // Following fontD has the different identifier from above three.
* Font fontD = new Font.Builder("/path/to/another/font").build();
*
* // Following fontE has different identifier from above four even the font path is the same.
* // To get the same identifier, please create new Font instance from existing fonts.
* Font fontE = new Font.Builder("/path/to/font").build();
*
*
*
* Here is an example of caching font object that has
*
*
* private LongSparseArray> mCache = new LongSparseArray<>();
*
* private Font getFontWeightVariation(Font font, int weight) {
* // Different collection index is treated as different font.
* long key = ((long) font.getSourceIdentifier()) << 32 | (long) font.getTtcIndex();
*
* SparseArray weightCache = mCache.get(key);
* if (weightCache == null) {
* weightCache = new SparseArray<>();
* mCache.put(key, weightCache);
* }
*
* Font cachedFont = weightCache.get(weight);
* if (cachedFont != null) {
* return cachedFont;
* }
*
* Font newFont = new Font.Builder(cachedFont)
* .setFontVariationSettings("'wght' " + weight);
* .build();
*
* weightCache.put(weight, newFont);
* return newFont;
* }
*
*
* @return an unique identifier for the font source data.
*/
public int getSourceIdentifier() {
return nGetSourceId(mNativePtr);
}
/**
* Returns true if the given font is created from the same source data from this font.
*
* This method essentially compares {@link ByteBuffer} inside Font, but has some optimization
* for faster comparing. This method compares the internal object before going to one-by-one
* byte compare with {@link ByteBuffer}. This typically works efficiently if you compares the
* font that is created from {@link Builder#Builder(Font)}.
*
* This API is typically useful for checking if two fonts can be interpolated by font variation
* axes. For example, when you call {@link android.text.TextShaper} for the same
* string but different style, you may get two font objects which is created from the same
* source but have different parameters. You may want to animate between them by interpolating
* font variation settings if these fonts are created from the same source.
*
* @param other a font object to be compared.
* @return true if given font is created from the same source from this font. Otherwise false.
*/
private boolean isSameSource(@NonNull Font other) {
Objects.requireNonNull(other);
ByteBuffer myBuffer = getBuffer();
ByteBuffer otherBuffer = other.getBuffer();
// Shortcut for the same instance.
if (myBuffer == otherBuffer) {
return true;
}
// Shortcut for different font buffer check by comparing size.
if (myBuffer.capacity() != otherBuffer.capacity()) {
return false;
}
// ByteBuffer#equals compares all bytes which is not performant for e.g. HashMap. Since
// underlying native font object holds buffer address, check if this buffer points exactly
// the same address as a shortcut of equality. For being compatible with of API30 or before,
// check buffer position even if the buffer points the same address.
if (getSourceIdentifier() == other.getSourceIdentifier()
&& myBuffer.position() == otherBuffer.position()) {
return true;
}
// Unfortunately, need to compare bytes one-by-one since the buffer may be different font
// file but has the same file size, or two font has same content but they are allocated
// differently. For being compatible with API30 ore before, compare with ByteBuffer#equals.
return myBuffer.equals(otherBuffer);
}
/** @hide */
public boolean paramEquals(@NonNull Font f) {
return f.getStyle().equals(getStyle())
&& f.getTtcIndex() == getTtcIndex()
&& Arrays.equals(f.getAxes(), getAxes())
&& Objects.equals(f.getLocaleList(), getLocaleList())
&& Objects.equals(getFile(), f.getFile());
}
@Override
public boolean equals(@Nullable Object o) {
if (o == this) {
return true;
}
if (!(o instanceof Font)) {
return false;
}
Font f = (Font) o;
// The underlying minikin::Font object is the source of the truth of font information. Thus,
// Pointer equality is the object equality.
if (nGetMinikinFontPtr(mNativePtr) == nGetMinikinFontPtr(f.mNativePtr)) {
return true;
}
if (!paramEquals(f)) {
return false;
}
return isSameSource(f);
}
@Override
public int hashCode() {
return Objects.hash(
getStyle(),
getTtcIndex(),
Arrays.hashCode(getAxes()),
// Use Buffer size instead of ByteBuffer#hashCode since ByteBuffer#hashCode traverse
// data which is not performant e.g. for HashMap. The hash collision are less likely
// happens because it is unlikely happens the different font files has exactly the
// same size.
getLocaleList());
}
@Override
public String toString() {
return "Font {"
+ "path=" + getFile()
+ ", style=" + getStyle()
+ ", ttcIndex=" + getTtcIndex()
+ ", axes=" + FontVariationAxis.toFontVariationSettings(getAxes())
+ ", localeList=" + getLocaleList()
+ ", buffer=" + getBuffer()
+ "}";
}
/** @hide */
public static Set getAvailableFonts() {
// The font uniqueness is already calculated in the native code. So use IdentityHashMap
// for avoiding hash/equals calculation.
IdentityHashMap map = new IdentityHashMap<>();
for (long nativePtr : nGetAvailableFontSet()) {
Font font = new Font(nativePtr);
map.put(font, font);
}
return Collections.unmodifiableSet(map.keySet());
}
@CriticalNative
private static native long nGetMinikinFontPtr(long font);
@CriticalNative
private static native long nCloneFont(long font);
@FastNative
private static native ByteBuffer nNewByteBuffer(long font);
@CriticalNative
private static native long nGetBufferAddress(long font);
@CriticalNative
private static native int nGetSourceId(long font);
@CriticalNative
private static native long nGetReleaseNativeFont();
@FastNative
private static native float nGetGlyphBounds(long font, int glyphId, long paint, RectF rect);
@FastNative
private static native float nGetFontMetrics(long font, long paint, Paint.FontMetrics metrics);
@FastNative
private static native String nGetFontPath(long fontPtr);
@FastNative
private static native String nGetLocaleList(long familyPtr);
@CriticalNative
private static native int nGetPackedStyle(long fontPtr);
@CriticalNative
private static native int nGetIndex(long fontPtr);
@CriticalNative
private static native int nGetAxisCount(long fontPtr);
@CriticalNative
private static native long nGetAxisInfo(long fontPtr, int i);
@FastNative
private static native long[] nGetAvailableFontSet();
}