api: Add API to query available font families and styles

[peterhorvath111]

Description

Fixes #4503.

Add an API to query available fonts based on family and style name. The API can be used to build a UI where users can select a font from a list.

• font_families(): Return the list of available font families in alphabetical order.
• font_styles(family): Return the list of available font styles of a given font family.
• font_filename(family, style): Return the font filename that defines the font with the given family and style.

Checklist:

• I have read the contribution guidelines.
• I have updated the documentation, if applicable. (Check if there is no
  need to update the documentation, for example if this is a bug fix that
  doesn't change the API.)
• I have ensured that the change is tested somewhere in the testsuite
  (adding new test cases if necessary).
• If I added or modified a C++ API call, I have also amended the
  corresponding Python bindings (and if altering ImageBufAlgo functions, also
  exposed the new functionality as oiiotool options).
• My code follows the prevailing code style of this project. If I haven't
  already run clang-format before submitting, I definitely will look at the CI
  test that runs clang-format and fix anything that it highlights as being
  nonconforming.

[lgritz]

Whoa, what's up with this?

[peterhorvath111]

Oops, my bad, I don't know what happened there. Fixed now.

[lgritz]

Are you aware of the existing OIIO::getattribute() queries related to fonts?

/// - `string font_list`
/// - `string font_file_list`
/// - `string font_dir_list`
///
///   A semicolon-separated list of, respectively, all the fonts that
///   OpenImageIO can find, all the font files that OpenImageIO can find (with
///   full paths), and all the directories that OpenImageIO will search for
///   fonts.  (Added in OpenImageIO 2.5)

Historically, we've tended to avoid adding new single-use API calls for individual queries, instead preferring to just add new tokens that getattribute recognizes to cover as many cases as possible.

Your font_families() and font_styles() are trivially amenable to this approach, since they just return a list of strings. The font_filename() is a little trickier, but we could probably do it by accepting special query names composed of "font_filename:FAMILY:STYLE" and parsing out the family and style name. Internally, they would still be implemented by more or less the functions you implemented but they would be turned into something in the pvt namespace and hidden from public headers.

I'm not saying I'm necessarily set against doing it as functions as you have... but I wanted to give you the chance to consider sticking with the idiom we've been using, which I think has been successful in keeping ABI churn to a minimum. For functionality that's never really in a performance critical loop, it's really easy to add, remove, backport, or change the name or meaning of these tokens without any hard compatibility breaks, compared to the approach where a different set of exposed API functions is required.

[peterhorvath111]

I don't mind switching to getattribute() queries, if that's the preferred approach.

[peterhorvath111]

API functions are converted to the following getattribute() queries:

• font_family_list: Return a semicolon-separated list of all available font families.
• font_style_list:family: Return a semicolon-separated list of all available font styles of a given font family.
• font_filename:family:style: Return the font filename that defines the font of the given family and style.

[lgritz]

I like! Thanks.

[lgritz]

Because 3.0.0 is already marked as a release candidate, my goal is only to merge critical bug fixes for the final non-rc tag on Friday. So I'll merge this into main today, then backport it into the dev-3.0 branch after tagging on Friday, so technically this will be released as part of the next (3.0.1) patch release.

If it's really important to you to get this in Friday's first 3.0.0 final release, then I can do it at essentially no real risk (since as far as public API, all this does is add some new getattribute query tokens and changes no other behavior, which was the whole point!). But if you can wait for 3.0.1 or operate from main for now, then I think it's better release policy to not add anything unnecessary once an RC is declared, no matter how harmless it appears.

[ThiagoIze]

Waiting for 3.0.1 is perfectly fine for us.