Remove useless scale from text HUD element documentation

[Wuzzy2]

Fixes #17029.

The scale field is removed from the documentation for text HUD elements because this field appears to do absolutely nothing after various tests.

Even after considering @SmallJoker’s comments in #17029, I still have not managed to find any HUD definition where scale changes anything. So I assume it really does nothing, as I suspected.

If the intention of scale was to clip text out of a bounding box, it is not working as promised, so the documentation should not claim it anymore.

This documentation can always be added back later if some functional bounding box feature is added.

NEW CHANGE: Additionally, an useless size variable in hud.cpp was removed.

To do

This PR is ready for review.

How to test

Read the changed files.

Test if HUD text still works.

[cx384]

Even after considering @SmallJoker’s comments in #17029, I still have not managed to find any HUD definition where scale changes anything. So I assume it really does nothing, as I suspected.

Indeed, scale does not change anything, because for the draw call hcenter and vcenter is false. So only the UpperLeftCorner of the position is relevant which does not get changed by scale.

Please also remove it in the cpp code to avoid confusion e.g. apply this:
0001-Remove-text-hud-scale-in-hud.cpp.patch

[Wuzzy2]

Wait a minute … I just realized something when looking at the code.

size is a core::rect and is used here:

ttfont->draw(line, size + pos + offset + offs + line_offset);

and here:

textfont->draw(line.c_str(), size + pos + offset + offs + line_offset, color);

According to the Irrlicht documentation, when you add a core::position2d to a core::rect, it means:

move right by given numbers

https://irrlicht.sourceforge.io/docu/classirr_1_1core_1_1rect.html#a699b98aff4bf8b7d92cef6d3c940354f

I interpret that the rectangle origin position is shifted by pos. Since this position (of size) is always (0,0), this is a no-op. This explains why the scale setting does nothing.

I will therefore remove size entirely, as it's essentially dead code.

[Wuzzy2]

• Removed size from hud.cpp
• Added an explicit warning that scale should not be used in lua_api.md because probably lots of existing code will still have the scale (current documentation explicitly recommends {x = 100, y = 100}) and it was in the documentation for a very long time

Please test the PR because it now contains a code change. (works on my machine)

By the way: The draw function in Irrlicht includes an explicit clip parameter that we could use later to implement actual clipping. https://irrlicht.sourceforge.io/docu/classirr_1_1gui_1_1_i_g_u_i_font.html#af5627e546c474f31260fe671c24f9a33

Probably too late/risky for 5.16.0 tho.

[cx384]

I interpret that the rectangle origin position is shifted by pos. Since this position (of size) is always (0,0), this is a no-op. This explains why the scale setting does nothing.

No, it gets added to both UpperLeftCorner and LowerRightCorner see:

luanti/irr/include/rect.h

Lines 60 to 65 in bb7fcd3

	rect<T> &operator+=(const position2d<T> &pos)
	{
	UpperLeftCorner += pos;
	LowerRightCorner += pos;
	return *this;
	}

I will therefore remove size entirely, as it's essentially dead code.

Yes, as I wrote before, only the UpperLeftCorner is relevant in our draw calls, but this is only because hcenter and vcenter is false. See

luanti/src/irrlicht_changes/CGUITTFont.cpp

Line 582 in bb7fcd3

if (hcenter || vcenter)

luanti/src/irrlicht_changes/CGUITTFont.cpp

Line 622 in bb7fcd3

if (hcenter)

luanti/irr/src/CGUIFont.cpp

Lines 319 to 323 in bb7fcd3

	if (hcenter)
	offset.X += (position.getWidth() - textDimension.Width) >> 1;
	if (vcenter)
	offset.Y += (position.getHeight() - textDimension.Height) >> 1;

luanti/irr/src/CGUIFont.cpp

Line 351 in bb7fcd3

if (hcenter) {

[Wuzzy2]

I’ve updated this PR by just re-applying the original suggested patch again.

[appgurueu]

only some typos

[Wuzzy2]

Done.