Text schema-level feedback

[tcauchois]

Hi all,

I've got some notes on the Autodesk text proposal. This issue is specifically focused on USD schema issues; I'm planning to file another issue about the hydra implementation. Hoping some text-knowledgeable folks can sanity check this but some things that jumped out at me:

Feedback on SimpleText:

• I was surprised to see textMetricsUnit as a member of SimpleText, and textHeight as a member of TextStyle. These seem like they want to be authored on the same prim. Assuming that a standard scene will have SimpleText with no TextStyle (i.e. renderer's choice) or a bunch of text pointing at the same TextStyle, it seems like of the things to vary across text prims, textHeight is maybe the most likely?
• renderer seems like an implementation detail that's not appropriate at this level of schema. I like the idea of delegating text -> geometry transformations to a plugin, to make it easier to integrate with the local text library, but that seems like something that should be resolved at build time, not at per-prim processing time. It's possible I'm missing something here, though?
• For completeness, we should list the relationships here to a TextStyle prim, TextLayoutPrim, etc.

Feedback on TextStyle:

• fontType, once again, seems like an implementation detail that doesn't belong at this level of schema. Given the text implementations we've compiled against and the font search paths, we should choose the right font file based on the "typeface" parameter. If the choice involves other elements of TextStyle, or something about how we're rendering, those choices can drive the font selection.
• A question for more text-knowledgeable folks: are bold and weight redundant, or is it pretty standard to expose both? I appreciate that the proposal discusses how to resolve between them.
• textWidthFactor/charSpacing: more consistent naming would be great here, maybe charWidthFactor and charSpacingFactor?

Feedback on TextLayout:

• direction isn't really adequate for internationalization; is it still worth having on SimpleText? It seems more useful for writing latin fonts in weird directions for engineering diagrams or something, but really using a text layout engine is the correct answer. Assuming you're not using a text layout engine, I'm assuming that we have a super simplistic layout engine which can draw the characters in neutral orientation but then move the curser right/left/up/down for the next character; if this is the intention, "defaultDir" is a bit of a trap because it requires layout knowledge of different scripts, which is precisely the thing we'd like to avoid here (seemingly).

Are TextStyle and TextLayout prims that SimpleText has a relationship to, or API schemas? It's unclear from the proposal. It seems likely to encounter a scene with a lot of text using the same styling, so making TextStyle a separate prim lets the scene define a global TextStyle and refer all of its SimpleText prims to that style, which seems appealing.

Feedback on MarkupText:

• The core concept here is text with multiple styles and some consideration to layout. Markup seems like an implementation, and MultilineText or LayoutText or something seems like a more appropriate name. Then markup becomes textData and markupLanguage becomes layoutMethod or something, with values including "plaintext" and "mtext".
• Same notes about textHeight and renderer.

Feedback on ColumnStyle:

• offset: columnOffset, for consistency?
• margins: what order are these in?
• blockAlignment: verticalAlignment seems like a more understandable name.
• direction/lineFlowDirection: first of all, these are confusing names. Could you have characterDirection and lineDirection to distinguish between them? These also seem like weird additions to ColumnStyle, and a better fit for TextLayout or MultilineTextLayout or something. I'd also imagine you'd want an option to let a layout engine handle both.
• In order to have multiple columns, you either need MarkupText to have a relationship to one-or-more column prims, or you need a multi-apply ColumnStyle API schema. It seems tidy to be able to use a multi-apply schema to define the columns right on the text prim (since they are probably intrinsically linked to the text contents and not shareable); and then have a MarkupText attribute columnOrder that lists the instance names in order.

Feedback on ParagraphStyle:

• leftIndent, rightIndent: are these redundant with ColumnStyle margins?
• paragraphAlignment: horizontalAlignment?
• Same notes about MarkupText having a relationship to multiple ParagraphStyles or having a multi-apply ParagraphStyleAPI schema and an ordering attribute. I like the API schemas here and for ColumnStyle since I view this formatting as logically part of the text data, as opposed to TextStyle which might be shared by many text primitives.

Thanks!
Tom

[meshula]

I'll take /one/ of them :)

if you've got a piece of paper, the paper defines the root coordinate system and metric

margins are /effectively/ the viewport on the paper, and the first layer of coordinate system under the root system

indent is a coordinate system under the margins coordinate system, or within another indent coordinate system (although I haven't mentally parsed whether indents nest in this proposal)

[PierreWang]

@tcauchois Thank you for your comment.

• For the textMetricsUnit, it is something related with the MarkupText. MarkupText can have TextStyle, ParagraphStyle and ColumnStyle. Each style has some properties related with metrics unit. It will be strange that the unit is different for a TextStyle and a ParagraphStyle that is bound by the same MarkupText. So the unit is a property of the primitive, not the style. Or maybe we can put it in a higher hierarchy (in a scope?). For example, several primitives in the scene are for printing so the unit for all of them should be "publishing point".

• For the renderer, just want to know if it is possible to have multiple text renderers. If there is only one renderer, or if the renderer is decided by the font type, we don't need the renderer in schema. But if it is possible to have several renderers together (for example, an texture atlas renderer and an SDF based renderer), and user may select one of them, we need to provide a way to do the selection.

• For fontType, it is still possible that we have the same typeface with different font type. For example, there may be both gothic.ttf and gothic.shx in the font folder. We need to distinguish them.

Sorry I haven't checked the comments after fontType. I will continue the discussion tomorrow.

[PierreWang]

@tcauchois Continue with the previous comments.

• For bold and weight, this is my understanding.
  Bold is a property of the font. Not every font has a corresponding "bold" style font, but some font library can use special technique to create a "bold" font from a normal font. "bold" and "italic" style are the most common style that can be applied to a font.
  There are also other styles which are related with the strokes, such as "thin", "light", "extra light", "semibold" and so on. CSS has a mapping from font weight to the style, and GDI uses the same mapping. For example, the weight 100 is mapped to "thin" style, and 700 is mapped to "bold" style. If the requested weight can not be achieved, a nearest style will be chosen. This is where the font weight comes from.
  But most of these styles are not commonly used. And it is not convenient that we require the user to remember that 400 is mapped to normal and 700 is mapped to bold. So in my opinion, by default we disable the "weight" property. This property is by default setting to zero. In that case, we use the "bold" property to determine if we use a bold font or not. If the user need the weight property, they can set it to a non-zero value, and in that case, the "bold" property will be ignored.

• textWidthFactor/charSpacing I agree with you. Indeed in the implementation the variable names are textWidthFactor and charSpacingFactor.

• direction is for the text primitive whose direction is not the same as the default one. The Latin languages normally put the characters from left to right, while Arabic usually puts the characters from right to left. The Japanese characters are lay from top to bottom by default. There is no default setting for the direction, so we need the "defaultDir" setting. And we still need the direction property for SimpleText, because many languages can have non-default layout. For example, it is also common to see a left-to-right Japanese text string.

[PierreWang]

• TextStyle and TextLayout should be API schemas. Currently we also add TextStyleAPI and TextLayoutAPI to apply the prim to the SimpleText or MarkupText prim. I think we can merge the TextStyle and TextStyleAPI. And the same for TextLayout.

• I think markup is not just for the layout. It may be converted to a style, or layout.

• I agree most of the feedbacks on ColumnStyle. But I think for the alignments, we'd better use blockAlignment. One reason is that the paragraphAlignment is not always horizontal. The paragraphs could be vertical. As a result, verticalAlignment may be ambiguous.

• leftIndent and rightIndent are different from margins. If you can open a word, you will see the configuration for indents and margins in the Layout pane. They are different.