{"id":13529067,"url":"https://github.com/maltaisn/msdf-gdx","last_synced_at":"2025-04-01T14:34:01.755Z","repository":{"id":57726423,"uuid":"206877318","full_name":"maltaisn/msdf-gdx","owner":"maltaisn","description":"Provides lightweight utilities to draw MSDF text on LibGDX","archived":false,"fork":false,"pushed_at":"2023-12-21T22:21:34.000Z","size":11302,"stargazers_count":34,"open_issues_count":2,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-02T15:36:31.846Z","etag":null,"topics":["bmfont","distance-field","libgdx","library","msdf","text-rendering"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maltaisn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-09-06T21:34:20.000Z","updated_at":"2024-09-15T03:46:24.000Z","dependencies_parsed_at":"2024-01-07T12:23:15.490Z","dependency_job_id":"fa34ca37-ff5e-4138-8c02-0f8e7906adc6","html_url":"https://github.com/maltaisn/msdf-gdx","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maltaisn%2Fmsdf-gdx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maltaisn%2Fmsdf-gdx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maltaisn%2Fmsdf-gdx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maltaisn%2Fmsdf-gdx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maltaisn","download_url":"https://codeload.github.com/maltaisn/msdf-gdx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246655576,"owners_count":20812659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bmfont","distance-field","libgdx","library","msdf","text-rendering"],"created_at":"2024-08-01T07:00:32.515Z","updated_at":"2025-04-01T14:33:56.740Z","avatar_url":"https://github.com/maltaisn.png","language":"Kotlin","funding_links":[],"categories":["Resources"],"sub_categories":["User Interface"],"readme":"# MSDF font library for LibGDX\nProvides lightweight utilities to draw MSDF (multi-channel signed distance field) \ntext on LibGDX. See LibGDX's [Distance field fonts][sdf-libgdx] wiki page for more information on\nsingle channel SDF font. It also provides integration with scene2d and AssetManager. \nThe library is written in Java but was also designed to be used seemlessly from Kotlin.\n\n![Demo](demo.gif)\n\n[MSDFA font][msdfa] files are used to draw text. This format combines both\nmulti channel (MSDF) and single channel (SDF) distance fields. \nThe MSDF is encoded in 3 channels (RGB) and SDF is encoded in the alpha channel.\nEach distance field has its advantages: MSDF is used to accurately draw glyphs with \nsharp corners at arbitrarly large sizes and SDF is used for shadow effects to keep \nround corners.\n\n## Usage\n\n##### Gradle dependency\n```\nimplementation(\"com.maltaisn:msdf-gdx:X.Y.Z\")\n```\nReplace `X.Y.Z` with the lastest version: [![Maven Central](https://img.shields.io/maven-central/v/com.maltaisn/msdf-gdx)](https://search.maven.org/artifact/com.maltaisn/msdf-gdx)\n\n###### HTML\n\nYou need to add the sources dependency to the html project (`project(\":html\")`) inside `build.gradle`:\n````groovy\nimplementation(\"com.maltaisn:msdf-gdx:X.Y.Z:sources\")\n````\n\nYou need also to add a `inherit` to your `GdxDefinition.gwt.xml` file:\n````xml\n\u003cinherits name=\"com.maltaisn.msdf-gdx\"/\u003e\n````\n\n#### MsdfFont\nThe shader needs a `MsdfFont` object to work, which is a simple wrapper around BitmapFont.\nThe `MsdfFont` can be created from an existing BitmapFont or from a *.fnt* file. \nYou can also use the AssetManager to load one:\n```java\n// Load the font with the asset manager.\nAssetManager manager = new AssetManager();\nmanager.setLoader(MsdfFont.class, new MsdfFontLoader(new InternalFileHandleResolver()));\nmanager.load(\"roboto.fnt\", MsdfFont.class);\nmanager.finishLoading();\nMsdfFont font = manager.get(\"roboto.png\");\n\n// Add the font to a skin.\nSkin skin = new Skin();\nskin.add(\"roboto\", font);\n```\nWhen creating a font, the glyph size and the distance range must be specified. When using the `MsdfFontLoader`, \nthis can either be specified directly in the *.fnt* file or with a `MsdfFontParameter` loader parameter.\n\n#### FontStyle\nFont styles can be created by code:\n```java\nFontStyle fontStyle = new FontStyle()\n        .setFontName(\"roboto\")\n        .setColor(Color.WHITE)\n        .setSize(48f);\n```\nOr in a skin file:\n```libgdxjson\ncom.maltaisn.msdfgdx.FontStyle: {\n    titleFontStyle: {\n        fontName: roboto\n        color: { hex: #ffffff }\n        size: 48\n    }\n}\n```\n\nHere's the list of options in a font style:\n- **fontName**: Font name. When used with `MsdfLabel`, the font name is the name of the `MsdfFont` \n  in the skin used to create the label.\n- **size**: Text size in pixels.\n- **weight**: Text weight (light, bold) between -0.5 and 0.5.\n- **color**: Text color\n- **allCaps**: All caps text is uppercased automatically when used in `MsdfLabel`.\n- **shadowClipped**: Whether shadow should appear behind glyph if glyph color is translucent.\n- **shadowColor**: Color of the shadow. Default is transparent.\n- **shadowOffset**: Shadow offset in pixels relative to glyph size.\n- **shadowSmoothing**: Shadow smoothing between 0 and 0.5.\n- **innerShadowColor**: Inner shadow color. Default is transparent.\n- **innerShadowRange**: Inner shadow range from 0 to 0.5.\n\n#### MsdfLabel\nA subclass of Label used to render MSDF text in scene2d. The label is constructed using a skin instance\nand a font style. The skin must contain the shader under the \"default\" name and the `MsdfFont`.\n```java\nSkin skin = new Skin();\nskin.add(\"default\", new MsdfShader());\nskin.add(\"roboto\", new MsdfFont(Gdx.files.internal(\"roboto.fnt\"), 32f, 5f));\n\nFontStyle fontStyle = new FontStyle()\n        .setFontName(\"roboto\")\n        .setSize(48f);\nMsdfLabel label = new MsdfLabel(\"My text\", skin, fontStyle);\nstage.addActor(label);\n```\n\nLabel is the only widget provided by the library. You can make your own MsdfTextField implementation\nby applying the code below for drawing text. However, `Label` is the only LibGDX widget to provide\na `setFontScale`, so other widgets may not be able to draw MSDF text by subclassing. \n(see [this issue](https://github.com/libgdx/libgdx/issues/5719))\n\n#### Drawing text\nYou can also draw text without using MsdfLabel:\n```java\nMsdfShader shader = skin.get(MsdfShader.class);\nMsdfFont font = skin.get(\"roboto\", MsdfFont.class);\nBitmapFont bmfont = font.getFont();\n\nbatch.setShader(shader);\nbmfont.getData().setScale(fontStyle.getSize() / font.getGlyphSize());\nshader.updateForFont(font, fontStyle);\nbmfont.draw(batch, \"My text\", 100f, 100f);\nbatch.setShader(null);\n```\n\n## Generating fonts\nHere are your options:\n- I made a small utility for generating font files. It works great as far as I have tested \nit but it might not be perfect. **[Check it out here][msdf-gdx-gen]**.\n- You can also generate MSDF and SDF font files with other programs and\ncombine them manually with an image editing program. [A tutorial is available here][gen-util-old].\n- The library can also render plain MSDF/SDF just fine and without having to change \nanything. The alpha channel must be encoded with SDF for shadows to work though.\n\n## Changelog\nSee [changelog](CHANGELOG.md).\n\n## License\n- Code is licensed under [Apache License, Version 2.0](LICENSE).\n- Test font (Roboto) is licensed under Apache License, Version 2.0.\n\n## Contributing\nDon't hesitate to open a pull request if you feel like something needs an improvement.\nJust be sure to follow existing code style.\n\n### References\n- [msdfgen][msdfgen] by Chlumsky who developed the MSDF technique.\n- [msdf-bmfont-xml][msdf-bmfont-xml] by soimy, used to create font texture atlas.\n- [SmartEdge's MSDFA font][msdfa], explains the advantages of MSDFA vs MSDF.\n- [Font effects shader example][effects-shader] by Chlumsky, used to develop shadow effect.\n- [Improved antialiasing shader][better-aa] used by the library.\n- [LibGDX's tutorial on distance field fonts][sdf-libgdx] for basic distance field usage.\n\n\n[msdfa]: http://inter-illusion.com/assets/I2SmartEdgeManual/SmartEdge.html?WhatSDFFormattouse.html\n[msdf-bmfont-xml]: https://github.com/soimy/msdf-bmfont-xml\n[msdfgen]: https://github.com/Chlumsky/msdfgen\n[xml-to-fnt]: utils/bmfont_converter.py\n[charset]: utils/charset.txt\n[charset-wiki]: https://en.wikipedia.org/wiki/ISO/IEC_8859-15\n[sdf-libgdx]: https://github.com/libgdx/libgdx/wiki/Distance-field-fonts\n[effects-shader]: https://gist.github.com/Chlumsky/263c960ae0a7df59afc2da4051eb0553\n[better-aa]: https://github.com/Chlumsky/msdfgen/issues/36\n[msdf-gdx-gen]: https://github.com/maltaisn/msdf-gdx-gen\n[gen-util-old]: utils/README.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaltaisn%2Fmsdf-gdx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaltaisn%2Fmsdf-gdx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaltaisn%2Fmsdf-gdx/lists"}