Could we update flag's comment with something that indicates embedders should move away from it? Similarly, could we add a similar comment to FlutterSemanticsFlag recommending you use FlutterSemanticsFlags instead

If the goal is to move off flags and replace it with flags2, then:

1. Definitely add a comment telling the reader to migrate to flags2
2. Consider renaming flags to flags__unused__ to force anyone building against the embedder to migrate.

Even with the field rename, We must continue populating the existing flags field from the new struct so that we don't break existing embedders who drop in a new engine shared lib.

This will need a struct_size member to make ABI compatibility easier for custom embedders.

For more info on ABI compatibility requirements this file has:

For an example of how struct_size is used:

Does that mean we can never change the size of the struct even if we have more flags later?

@chunhtai If you have to take a guess, how many semantics flags will we eventually need?

No you can add more members in the future, but custom embedders will use struct_size to check whether it can access that new member.

Let's say the flags have struct size 4. You add a new flag that makes the struct size 8. A custom embedder must not access that new flag unless the struct size is >= 8.

However, we cannot remove or reorder members from the struct.

if we can't change the size of the struct, we still need to predict how many semantics flags we need in the future right?

struct_size is always populated with sizeof(FlutterSemanticsFlags), so it will increase as fields are added.

This is a bit related to why fields must always be added at the end of a struct and why we can never reorder fields. Embedders built against older versions of the engine will be reading these fields from the memory offsets within the struct from the engine version they built against. If the embedder author drops in a new engine shared lib, those offsets must still match correctly.

Whenever we look up fields in embedder.cc, we use a SAFE_ACCESS(struct_instance, field_name, default_value) macro. That macro checks that the offset of field_name + sizeof(struct_instance->field_name) is less than struct_instance.struct_size and if not, resolves to default_value.

thanks for explaining this!

Could we snake case these? Something like:

Yes -- these must use C/C++ style. So is_checked, has_checked_state, etc.

do we need to call the constructor? I think just

FlutterSemanticsFlags flags;

will be fine?

also why 0?

I'm calling the constructor here to make sure the flags are all initialized to false/0 by default.
I think if it's just FlutterSemanticsFlags flags;, it's not guaranteed to be all 0s

A little more idiomatic:

FlutterSemanticsFlags flags = FlutterSemanticsFlags{};

But, as pointed out above, even more idiomatic in modern C++:

auto flags = FlutterSemanticsFlags{
  .is_text_field = true,
  .is_readonly = true,
};

And yes; as @hannah-hyj says, this is important since locals are uninitialised in C++, so without this, it'll be populated with whatever memory happens to be on the stack at the time.

nit: This is safe as-is, but I'd put this at the end to avoid splitting up actions_ and action_pointers_.

Instead, use designated initialiser syntax:

const FlutterSemanticsFlags convertToFlutterSemanticsFlags(
    const SemanticsFlags& source) {
  return {
    .has_checked_state = source.hasCheckedState,
    .is_checked = source.isChecked,
    // ...
    .is_required = source.isRequired,
  };
}

I imagine in both cases the compiler is clever enough to apply return value optimisation, which ensures the return object is constructed directly in the memory address of the caller rather than copied, but this way is more idiomatic and avoids declaring a local at all.