Added text rendering utilities. #183

CHANGELOG.md

@@ -11,6 +11,7 @@
 - **[FEATURE]** (`ktx-async`) Added `RenderingScope` factory function for custom scopes using rendering thread dispatcher.
 - **[FEATURE]** (`ktx-graphics`) Added `LetterboxingViewport` from `ktx-app`.
 - **[FEATURE]** (`ktx-graphics`) Added `takeScreenshot` utility function that allows to save a screenshot of the application.
+- **[FEATURE]** (`ktx-graphics`) Added `BitmapFont.center` extension method that allows to center text on an object.
 - **[FEATURE]** (`ktx-graphics`) Added `Camera` utilities.
     - `center` extension method allows to center the camera's position to screen center or the center of the chosen rectangle.
     - `moveTo` extension method allows to move the camera immediately at the chosen target position with optional offset.

graphics/README.md

@@ -22,6 +22,8 @@ overriding with optional, named parameters.
 also be passed to the `Batch.use` extension function to have it automatically applied to the batch's projection matrix.
 - `begin` extension methods that automatically set projection matrix from a `Camera` or `Matrix4` were added to `Batch`.
 - `takeScreenshot` allows to easily take a screenshot of current application screen.
+- `BitmapFont.center` extension method allows to calculate center position of text in order to draw it in the middle
+of a chosen object.
 
 #### `ShapeRenderer`
 
@@ -183,6 +185,25 @@ import ktx.graphics.takeScreenshot
 takeScreenshot(Gdx.files.external("mygame/screenshot.png"))
 ```
 
+Finding out where to draw text in order to center it on a `Sprite`:
+
+```Kotlin
+import com.badlogic.gdx.graphics.g2d.BitmapFont
+import com.badlogic.gdx.graphics.g2d.Sprite
+import com.badlogic.gdx.math.Vector2
+import ktx.graphics.center
+
+fun getCenterAtSprite(
+  bitmapFont: BitmapFont, text: String, sprite: Sprite
+): Vector2 =
+  bitmapFont.center(
+    text,
+    // Note that x or y can be modified if you want a slight offset:
+    x = sprite.x, y = sprite.y,
+    width = sprite.width, height = sprite.height
+  )
+```
+
 Creating and customizing a new `LetterboxingViewport`:
 
 ```Kotlin
@@ -259,7 +280,7 @@ There are some general purpose LibGDX utility libraries out there, but most lack
 
 - [Kiwi](https://github.com/czyzby/gdx-lml/tree/master/kiwi) is a general purpose Guava-inspired LibGDX Java utilities
 library with some utilities similar to `ktx-graphics`.
-- [Cyberpunk](https://github.com/ImXico/Cyberpunk) framework provides similar utilities for cameras and screenshots.
+- [Cyberpunk](https://github.com/ImXico/Cyberpunk) framework provides similar utilities for cameras, text and screenshots.
 
 #### Additional documentation
 

graphics/src/main/kotlin/ktx/graphics/text.kt

@@ -0,0 +1,19 @@
+package ktx.graphics
+
+import com.badlogic.gdx.graphics.g2d.BitmapFont
+import com.badlogic.gdx.graphics.g2d.GlyphLayout
+import com.badlogic.gdx.math.Vector2
+
+/**
+ * Calculates center position of the chosen [text] written with this [BitmapFont] on an object
+ * with given [width] and [height] drawn at [x] and [y] coordinates.
+ *
+ * The passed [text] rendered with the selected [BitmapFont] at the returned coordinates should
+ * be in the middle of the object.
+ *
+ * Note that [x] and [y] are essentially an optional offset added to the calculated position.
+ */
+fun BitmapFont.center(text: String, width: Float, height: Float, x: Float = 0f, y: Float = 0f): Vector2 {
+  val layout = GlyphLayout(this, text)
+  return Vector2(x + (width - layout.width) / 2f, y + (height + layout.height) / 2f)
+}

graphics/src/test/kotlin/ktx/graphics/textTest.kt

@@ -0,0 +1,59 @@
+package ktx.graphics
+
+import com.badlogic.gdx.Gdx
+import com.badlogic.gdx.backends.lwjgl.LwjglFiles
+import com.badlogic.gdx.backends.lwjgl.LwjglNativesLoader
+import com.badlogic.gdx.graphics.g2d.BitmapFont
+import com.badlogic.gdx.utils.Array as GdxArray
+import com.nhaarman.mockitokotlin2.mock
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+
+/**
+ * Loads the .fnt settings file of the default LibGDX Arial font, but
+ * omits loading the textures. For testing purposes.
+ */
+class FakeFont : BitmapFont(
+  BitmapFontData(Gdx.files.classpath("com/badlogic/gdx/utils/arial-15.fnt"), true),
+  GdxArray.with(mock()),
+  true)
+{
+  override fun load(data: BitmapFontData?) {
+    // Do nothing.
+  }
+}
+
+class TextUtilitiesTest {
+  @Before
+  fun `setup files`() {
+    Gdx.files = LwjglFiles()
+  }
+
+  @Test
+  fun `should center text on a rectangle`() {
+    val font = FakeFont()
+    val width = 100f
+    val height = 200f
+
+    val position = font.center("text", width, height)
+
+    assertEquals(38.5f, position.x, 0.1f)
+    assertEquals(105.5f, position.y, 0.1f)
+  }
+  @Test
+  fun `should center text on a rectangle at given position`() {
+    val font = FakeFont()
+
+    val position = font.center("text", x = 100f, y = 200f, width = 100f, height = 200f)
+
+    assertEquals(138.5f, position.x, 0.1f)
+    assertEquals(305.5f, position.y, 0.1f)
+  }
+
+  @After
+  fun `dispose of files`() {
+    Gdx.files = null
+  }
+}