Optional Tighter Backing Field for Barks
Proposal by Geep, Dec 1, 2023

Background
==========
In the current version of TDM 2.12dev, subtitles now use a horizontally-compressed font. This has allowed a subtitle's horizontally-centered, translucent "backing field" to be less wide than with TDM 2.11, while still accommodating existing "verbosity story" subtitle lengths. This less-wide field (about 2/3rds of screen width) helpfully reduces the amount of peripheral screen real estate unnecessarily obscured when captions are shown. Besides leaving more of the 3D world visible, this leaves the HUD corner icons and associated text (for weapon and inventory item) unobscured at their default magnifications.

Work is continuing on English subtitles for barks, but there is light at the end of the tunnel. In pursuing this, I've strived to keep subtitles moderately limited in size (i.e., character count per line) and duration, in line with real-world captioning conventions. This is easier to do in a consistent manner with newly-created verbosity "speech" subtitles for barks, done as a separate project, than with "story" subtitles, largely the responsibility of FM authors or their successors.

Proposal Summary
================
Given the adopted size and duration limitations on bark subtitles (which are seen as applicable to verbosity "speech" and "effects" in general), it is possible to safely use an even narrower width (about 1/3rd of screen width) for these. This width has been used in my more-recent "testSubtitles..." FMs. To my mind, this smaller width is not just possible, but very strongly desirable, with these benefits:

- to further reduce screen real estate needlessly obscured.
- to be helpful to players that set HUD icon displays to higher magnifications.
- to provide a visual clue as to what is a "story" vocal clip and thus more important to hear/read/understand.

However, regarding that last point, I understand that others may prefer no differentiation between the field width of "story" and non-story subtitles. (There is of course already a major differentiator: non-story subtitles may be turned off entirely, leaving story on.) Therefore, I propose this is a choice that should be left up to the individual user.

A straightforward, concrete design for this follows. The implementation effort and added complexity are likely modest, comparable to most tasks that add a CVar.

Changes to Engine and Cvars
=========================
A new user-settable boolean Cvar, named here "subtitle_narrowfield_nonstory", is created with values:

0 = use wide backing field width for nonstory subtitles (i.e., of vebosity "speech" and "effects").
1= use narrow backing field width for nonstory subtitles

While I would prefer the default to be 1, as a compromise I can live with it being 0.

The engine would arrange that this would propagate to a .gui script as "gui::subtitle_narrowfield_nonstory". It is then used in conjunction with a triplet of variables, for each of the three subtitle position slots.  Specifically, let's call them "gui::subtitleN_nonstory", where N is the slot digit, and the possible values are:

0 = subtitle is story verbosity
1 = subtitle is speech or effects verbosity

This triplet is an evolution and simplification of the original request in bugtracker 6317, "New Feature - Tell gui the subtitle verbosity type". (Using booleans rather than enumerations makes it easy to do the math expression that sets "rect" size.)

Assumed Font Attributes
======================
In the latest TDM 2.12dev, font attributes in tdm_subtitles_common.gui are:

#define SUBTITLES_TEXT_SCALE 0.24
#define  SUBTITLES_TEXT_FONT "fonts/stone@aspect=16:9"

(It is possible that the scale should be 0.25, given that 48 pt is seleted with a scale of 1.0 and here 12 pt is probably intended. In any event...)

Let's assume we stick with that.

Desired Backing Field Widths
==========================
 In the current 2.12dev tdm_subtitles_message.gui, the field width is hardcoded at:

Field width (including inner padding) = 440
Left & right field margins = 100
Percentage of screen width = 68.75%

(This field width is less than the traditional TDM 2.11 value, which had to accommodate an uncompressed font:
Field width (including inner padding) = 620
Left & right field margins = 10
Percentage of screen width = 96.875%
)

It is proposed, to maximize compatibility, to continue keeping "story" subtitles with this field width. But other verbosities would have a user-choice of two widths:

When subtitle_narrowfield_nonstory == 0 (i.e., use wide field), use the same field width as for "story", given above.

When subtitle_narrowfield_nonstory == 1 (i.e., use narrow field), the field width becomes:

Field width (including inner padding) = 240
Left & right field margins = 200
Percentage of screen width = 37.5%

All the English subtitle texts for barks I have prepared will easily fit in this narrow field, given the font attributes.

Implementation in the .GUI
========================
In the proposed variation of tdm_subtitles_message .gui, the difference between the 2 field widths is expressed as a difference in the margin values, i.e., 200 -100 = 100, which is then toggled by the "..._nonstory" switch:

// SUBTITLE_MARGIN_DIFF's value will be 0 with a "story" subtitle or if Cvar subtitle_narrowfield_nonstory is false (0); otherwise, value is 100.
// 100 is the difference between horizontal field margin for nonstory (200) and story (100):
#define SUBTITLE_MARGIN_DIFF SUBTITLES_CONCAT3("(100 * gui::subtitle_narrowfield_nonstory * gui::subtitle", SUBTITLE_DIGIT, "_nonstory)")

Then SUBTITLE_MARGIN_DIFF is used throughout to define "rect" boundaries on-the-fly. The proposed file (whose syntax can't be tested without the requested engine changes) follows.

Revised tdm_subtitles_message.gui
================================
/**
 * stgatilov: This GUI header is included many times into subtitles GUI
 *
 * Mission Authors: DO NOT EDIT, INCLUDE OR OVERRIDE THIS FILE IN YOUR MISSION PK4.
 */

//must be defined outside: which subtitle slot to generate
//#define SUBTITLE_IDX 3
//#define SUBTITLE_DIGIT "3"

//preprocessor magic for composing window names
#define SUBTITLES_CONCAT3X(a, b, c) a##b##c
#define SUBTITLES_CONCAT3(a, b, c) SUBTITLES_CONCAT3X(a, b, c)

#define SUBTITLE_BASE_Y (370 - 50 * SUBTITLE_IDX)
#define SUBTITLE_NONEMPTY SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_nonempty")
#define SUBTITLE_ALPHA SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_alpha")
#define SUBTITLE_SPATIALIZED SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_spatialized")
#define SUBTITLE_LOCATION_X SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_locationXclamped")
#define SUBTITLE_LOCATION_Y SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_locationYclamped")

// SUBTITLE_MARGIN_DIFF's value will be 0 with a "story" subtitle or if Cvar subtitle_narrowfield_nonstory is false (0); otherwise, value is 100.
// 100 is the difference between horizontal field margin for nonstory (200) and story (100):
#define SUBTITLE_MARGIN_DIFF SUBTITLES_CONCAT3("(100 * gui::subtitle_narrowfield_nonstory * gui::subtitle", SUBTITLE_DIGIT, "_nonstory)")

windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesTextHolder, SUBTITLE_IDX)
{
	rect		100 + SUBTITLE_MARGIN_DIFF, SUBTITLE_BASE_Y, 440 - SUBTITLE_MARGIN_DIFF, 45
	backcolor	SUBTITLES_TEXT_BACKCOLOR
	bordercolor	SUBTITLES_TEXT_BORDERCOLOR
	visible		SUBTITLE_NONEMPTY

	windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesText, SUBTITLE_IDX)
	{
		// #5914: engine allows overflowing textbox size by one character
		// maximum character width is 17 at textscale 0.25, so leave horizontal padding 20 on the right
		rect		0, 0, 420 - SUBTITLE_MARGIN_DIFF, 45
		text		SUBTITLES_CONCAT("gui::subtitle", SUBTITLE_DIGIT)
		font		SUBTITLES_TEXT_FONT
		textscale	SUBTITLES_TEXT_SCALE
		textAlign	1
		forecolor	SUBTITLES_TEXT_FORECOLOR
	}
}

windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesLocationRing, SUBTITLE_IDX)
{
	rect		300, SUBTITLE_BASE_Y - 8, 20, 14
	visible		SUBTITLE_NONEMPTY && SUBTITLE_SPATIALIZED
	background	"guis/assets/common/subtitle_location_ring"
	matcolor	1,1,1,SUBTITLE_ALPHA
}
windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesLocationPoint, SUBTITLE_IDX)
{
	rect		307.5 - 9 * SUBTITLE_LOCATION_Y, SUBTITLE_BASE_Y - 4 - 6 * SUBTITLE_LOCATION_X, 5, 5
	visible		SUBTITLE_NONEMPTY && SUBTITLE_SPATIALIZED
	background	"guis/assets/common/frobhelper"
	matcolor	1,0,0,1
}

windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesDebugText, SUBTITLE_IDX)
{
	rect		100 + SUBTITLE_MARGIN_DIFF, SUBTITLE_BASE_Y + 40, 440 - SUBTITLE_MARGIN_DIFF, 45
	text		SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_debug")
	visible		SUBTITLE_NONEMPTY
	font		SUBTITLES_TEXT_FONT
	textscale	0.15
	forecolor	0.5,1,0.5,1
}


#undef SUBTITLE_IDX
#undef SUBTITLE_DIGIT

#undef SUBTITLES_CONCAT3X
#undef SUBTITLES_CONCAT3

#undef SUBTITLE_BASE_Y
#undef SUBTITLE_NONEMPTY
#undef SUBTITLE_ALPHA
#undef SUBTITLE_SPATIALIZED
#undef SUBTITLE_LOCATION_X
#undef SUBTITLE_LOCATION_Y

#undef SUBTITLE_MARGIN_DIFF

/**
 * stgatilov: This GUI header is included many times into subtitles GUI
 *
 * Mission Authors: DO NOT EDIT, INCLUDE OR OVERRIDE THIS FILE IN YOUR MISSION PK4.
 */

//must be defined outside: which subtitle slot to generate
//#define SUBTITLE_IDX 3
//#define SUBTITLE_DIGIT "3"

//preprocessor magic for composing window names
#define SUBTITLES_CONCAT3X(a, b, c) a##b##c
#define SUBTITLES_CONCAT3(a, b, c) SUBTITLES_CONCAT3X(a, b, c)

#define SUBTITLE_BASE_Y (370 - 50 * SUBTITLE_IDX)
#define SUBTITLE_NONEMPTY SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_nonempty")
#define SUBTITLE_ALPHA SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_alpha")
#define SUBTITLE_SPATIALIZED SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_spatialized")
#define SUBTITLE_LOCATION_X SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_locationXclamped")
#define SUBTITLE_LOCATION_Y SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_locationYclamped")

// SUBTITLE_MARGIN_DIFF's value will be 0 with a "story" subtitle or [planned] if Cvar subtitle_narrowfield_nonstory is false (0); otherwise, value is 100.
// 100 is the difference between horizontal field margin for nonstory (200) and story (100):
#define SUBTITLE_VERBOSITY SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_verbosity")
#define SUBTITLE_MARGIN_DIFF ((SUBTITLE_VERBOSITY) == 1 ? 0 : 100)
// To incorporate new CVar:
// #define SUBTITLE_MARGIN_DIFF "gui::subtitle_narrowfield_nonstory" * ((SUBTITLE_VERBOSITY) == 1 ? 0 : 100)

windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesTextHolder, SUBTITLE_IDX)
{
	rect		(100 + SUBTITLE_MARGIN_DIFF), SUBTITLE_BASE_Y, 440 - (2 * SUBTITLE_MARGIN_DIFF), 45
	backcolor	SUBTITLES_TEXT_BACKCOLOR
	bordercolor	SUBTITLES_TEXT_BORDERCOLOR
	visible		SUBTITLE_NONEMPTY

	windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesText, SUBTITLE_IDX)
	{
		// #5914: engine allows overflowing textbox size by one character
		// maximum character width is 17 at textscale 0.25, so leave horizontal padding 20 on the right
		rect		0, 0, 420 - (2 * SUBTITLE_MARGIN_DIFF), 45
		text		SUBTITLES_CONCAT("gui::subtitle", SUBTITLE_DIGIT)
		font		SUBTITLES_TEXT_FONT
		textscale	SUBTITLES_TEXT_SCALE
		textAlign	1
		forecolor	SUBTITLES_TEXT_FORECOLOR
	}
}

windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesLocationRing, SUBTITLE_IDX)
{
	rect		300, SUBTITLE_BASE_Y - 8, 20, 14
	visible		SUBTITLE_NONEMPTY && SUBTITLE_SPATIALIZED
	background	"guis/assets/common/subtitle_location_ring"
	matcolor	1,1,1,SUBTITLE_ALPHA
}
windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesLocationPoint, SUBTITLE_IDX)
{
	rect		307.5 - 9 * SUBTITLE_LOCATION_Y, SUBTITLE_BASE_Y - 4 - 6 * SUBTITLE_LOCATION_X, 5, 5
	visible		SUBTITLE_NONEMPTY && SUBTITLE_SPATIALIZED
	background	"guis/assets/common/frobhelper"
	matcolor	1,0,0,1
}

windowDef SUBTITLES_CONCAT3(SUBTITLES_NAMEPREFIX, SubtitlesDebugText, SUBTITLE_IDX)
{
	rect		100 + SUBTITLE_MARGIN_DIFF, SUBTITLE_BASE_Y + 40, 440 - (2 * SUBTITLE_MARGIN_DIFF), 45
	text		SUBTITLES_CONCAT3("gui::subtitle", SUBTITLE_DIGIT, "_debug")
	visible		SUBTITLE_NONEMPTY
	font		SUBTITLES_TEXT_FONT
	textscale	0.15
	forecolor	0.5,1,0.5,1
}


#undef SUBTITLE_IDX
#undef SUBTITLE_DIGIT

#undef SUBTITLES_CONCAT3X
#undef SUBTITLES_CONCAT3

#undef SUBTITLE_BASE_Y
#undef SUBTITLE_NONEMPTY
#undef SUBTITLE_ALPHA
#undef SUBTITLE_SPATIALIZED
#undef SUBTITLE_LOCATION_X
#undef SUBTITLE_LOCATION_Y

#undef SUBTITLE_VERBOSITY
#undef SUBTITLE_MARGIN_DIFF