What is the use of canvas' `drawTextRun`? How is it different from `drawText`?

Question

I try to understand the use of drawTextRun, but can't find how they differ from the normal drawText in canvas

The below codes

        canvas.drawTextRun(TEXT,
            0, TEXT.length,
            0, TEXT.length ,
            x, y, false, paint)

        canvas.drawText(TEXT,
            x, y, paint)

produces the same result. I try to play around the 0 and TEXT.length, but see not distinct different other than showing a shorter TEXT.

I read the help in https://developer.android.com/reference/kotlin/android/graphics/Canvas.html#drawTextRun%28kotlin.CharArray%2C+kotlin.Int%2C+kotlin.Int%2C+kotlin.Int%2C+kotlin.Int%2C+kotlin.Float%2C+kotlin.Float%2C+kotlin.Boolean%2C+android.graphics.Paint%29

It's description is Draw a run of text, all in a single direction, with optional context for complex text shaping. What is complex text shaping?

Answer 1

Apparently this function drawTextRun has no use for English or any language that has characters that doesn't change (e.g. Chinese).

It is only useful for language that has letters that will change pending on the existence of its neighboring letters. A good example is Arabic.

Do refer to Arabic Unicode, https://en.wikipedia.org/wiki/Arabic_script_in_Unicode, where the language.

e.g.

The 4 letters Arabic word عربى. (note Arabic is from Right to Left)

If written individually is ع ر ب ى

Notice the shape differs when it is by itself.

With the below code

    private val TEXT = "عربى"

    canvas.drawTextRun(TEXT,
        1, TEXT.length - 1,
        1, TEXT.length - 1,
        x, y,
        true, projectResources.paint)

It will produces

However if we change the context length, (i.e. the shown word is not complete, but does have it's neighboring first and last letters not shown)

    private val TEXT = "عربى"

    canvas.drawTextRun(TEXT,
        1, TEXT.length - 1,
        0, TEXT.length,
        x, y,
        true, projectResources.paint)

It will be as below

In short, despite the same letters are there, when with different context, it is writen differently.

Note: Thanks to https://hencoder.com/ui-1-3/ for shedding the light to understand the use of this method.