improve ktx-assets integration with gdx-freetype

[keturn]

As someone new to GDX and Kotlin, this one took me a while.

As the libgdx wiki describes, you need to set up FreetypeFontLoader on your AssetManager, since it doesn't register itself as a loader by default.

My transcription of that for ktx-assets looks like:

fun fontAssetManager(): AssetManager {
    val assetManager = AssetManager()
    val resolver = InternalFileHandleResolver()

    assetManager.setLoader<FreeTypeFontGenerator, FreeTypeFontGeneratorLoader.FreeTypeFontGeneratorParameters>(FreeTypeFontGeneratorLoader(resolver))

    val freeTypeLoader = FreetypeFontLoader(resolver)

    assetManager.setLoader<BitmapFont, FreetypeFontLoader.FreeTypeFontLoaderParameter>(freeTypeLoader, suffix = ".ttf")
    assetManager.setLoader<BitmapFont, FreetypeFontLoader.FreeTypeFontLoaderParameter>(freeTypeLoader, suffix = ".otf")

    return assetManager
}

and then that asset manager may be used like

val fontName = "myfont.otf"

val fontParameter = FreetypeFontLoader.FreeTypeFontLoaderParameter()
fontParameter.fontFileName = fontName
fontParameter.fontParameters.size = titleFontSize

val fontDescriptor = assetManager.load<BitmapFont>(fontName, fontParameter)

fontDescriptor.finishLoading()
font = titleFontDescriptor.asset

So I guess the areas of improvement include

• have ktx-assets (or ktx-freetype?) register the loaders
• a more Kotlinesque interface to FreeTypeFontLoaderParameter? The mutable parameter object you have to initialize as empty and then set the properties on seems not very safe.
• some documentation reminding users that yes, it's load<BitmapFont>, not load<FreetypeFont>. Because you're constructing a bitmap font out of this, even though the input is a TTF file.
  • (although if we got a text layout and renderer engine that didn't believe that all characters are independent rectangles you can slice out of a bitmap, that'd be cool too, but it sounds like gdx doesn't have one of those yet: Support for complex font rendering (Chinese, Arabic, ...) libgdx/libgdx#1589 )

[czyzby]

I agree that the loader registration syntax seems overcomplicated, this is exactly the kind of thing that KTX could improve. Not sure if another dependency in ktx-assets is a good idea - ktx-freetype module seems better. I'll look into it.

The mutable parameter object you have to initialize as empty and then set the properties on seems not very safe.

Welcome to LibGDX.

[czyzby]

io.github.libktx:ktx-freetype:1.9.7-SNAPSHOT should be available shortly. Can you check out the new module and see if that's what you meant?

[keturn]

Okay, with that my class looks like this:

const val TITLE_FONT = "neat-font.otf"

class MyScreen : KtxScreen {
    val batch = SpriteBatch()
    val assetManager = AssetManager()
    val titleFont: BitmapFont
    var titleFontSize = 48

    init {
        assetManager.registerFreeTypeFontLoaders()
        assetManager.loadFreeTypeFont(TITLE_FONT) {
            size = titleFontSize;
            color = Color.DARK_GRAY
        }
        assetManager.finishLoadingAsset(TITLE_FONT)
        titleFont = assetManager.get(TITLE_FONT)
    }
}

Which is certainly an improvement!

Some questions I'm left with:

1. assetManager.load<BitmapFont> returned a descriptor I could call finishLoading() on, but loadFreeTypeFont doesn't seem to return any such thing?
2. When I was reading Getting Started materials those few weeks ago, I got the strong impression that I'd want to define as many things as possible where they're first declared in the class definition, rather than having separate initialization code in the class's init method. Is that desirable & practical here?

[czyzby]

assetManager.load<BitmapFont> returned a descriptor I could call finishLoading()

Good point, I'll unify the API.

As for the initialization code: I guess it depends on your code style and project structure. I try to initialize vals as soon as possible and tend to avoid init blocks when it comes to most classes, but there are things like the GUI with Scene2D DSL which might as well be moved to the init. Some LibGDX APIs are not very Kotlin-friendly, like the create method in ApplicationListener which kind of prevents you from using val and forces to use the nullable var or lateinit var instead.

And be careful with finishLoadingAsset. What it does is block the thread and keeps on checking if that particular asset was loaded, without prioritizing it or anything. If you've scheduled multiple assets for loading, it might freeze your application. Take a look at AssetManager article and try to use field delegates instead (see ktx-assets readme).

[czyzby]

@keturn Have you tried using the latest snapshot with the API improvements?

I think the module is OK as it is, but I realized that AssetStorage (coroutines-based AssetManager alternative) could also use the same API improvements, so expect more updates.

[czyzby]

I think I'm done with both ktx-freetype (for LibGDX AssetManager) and ktx-freetype-async (for our AssetStorage from ktx-async. Both modules should be available through snapshots as 1.9.8-SNAPSHOT - since there have been quite a few changes and we still have not released 1.9.8 yet, I'd like to publish a release pretty soon. @keturn, @Jkly, would you mind checking out the FreeType utilities before the release?

[czyzby]

I've created a few mock applications to test this out and it seems to work without issues on desktop, with both OTF/TTF files and AssetManager/AssetStorage. The only thing that could have been improved was font generator API, so I added a small Kotlin DSL for it. I'm closing this for now, feel free to reopen if you think the modules could still use some improvements or more utilities.