Google Git
Sign in
fuchsia / fuchsia / refs/heads/main / . / src / graphics / display / lib / api-types-cpp
tree: 9a74df86b731fa664fde23a7f9ee25b94142b3fa [path history] [tgz]
  1. alpha-mode-test.cc
  2. alpha-mode.cc
  3. alpha-mode.h
  4. buffer-collection-id-test.cc
  5. buffer-collection-id.h
  6. buffer-id-test.cc
  7. buffer-id.h
  8. BUILD.gn
  9. config-stamp-test.cc
  10. config-stamp.cc
  11. config-stamp.h
  12. display-id-test.cc
  13. display-id.h
  14. display-timing-test.cc
  15. display-timing.cc
  16. display-timing.h
  17. driver-buffer-collection-id-test.cc
  18. driver-buffer-collection-id.h
  19. driver-buffer-id-test.cc
  20. driver-buffer-id.h
  21. driver-capture-image-id-test.cc
  22. driver-capture-image-id.h
  23. driver-image-id-test.cc
  24. driver-image-id.h
  25. driver-layer-id-test.cc
  26. driver-layer-id.h
  27. event-id-test.cc
  28. event-id.h
  29. frame-test.cc
  30. frame.cc
  31. frame.h
  32. image-buffer-usage-test.cc
  33. image-buffer-usage.h
  34. image-id-test.cc
  35. image-id.h
  36. image-metadata-test.cc
  37. image-metadata.h
  38. image-tiling-type-test.cc
  39. image-tiling-type.h
  40. layer-id-test.cc
  41. layer-id.h
  42. README.md
  43. transform-test.cc
  44. transform.cc
  45. transform.h
  46. vsync-ack-cookie-test.cc
  47. vsync-ack-cookie.h
src/graphics/display/lib/api-types-cpp/README.md

api-types-cpp is a library providing ergonomic C++ types for data structures used at API (FIDL / banjo) boundaries.

Coding conventions

  • Namespace: All types are defined in the display namespace.

  • Filename: Each type is declared and defined in separate type-name.h / type-name.cc files.

  • Documentation: Each type’s class-level documentation points to the related FIDL / banjo types. This library’s documentation does not duplicate the API contracts specified in the corresponding FIDL / banjo types.

  • One-to-many mapping: One type in this library may correspond to multiple FIDL or banjo types. The type’s documentation points to all related FIDL / banjo types.

  • Data structure naming: The library aims to reuse the FIDL vocabulary for type names and struct member names. FIDL names prevail in naming conflicts between FIDL and banjo. (The long-term conflict resolution is the removal of the banjo types.)

  • Conversion helpers: The library offers conversion helpers between library types and all related FIDL / banjo types. Conversion helpers that produce library types are named ToTypeName(). Conversion helpers that produce FIDL / Banjo types are named ToFidlTypeName() / ToBanjoTypeName().

Type design guidelines

A type defined in api-types-cpp may be an alias of the related FIDL C++ wire type. See AlphaMode for an aliasing example.

The library defines its own types when the code generated by the FIDL C++ wire binding is not sufficiently ergonomic. Some examples of ergonomic gaps in the FIDL generated code:

  • FIDL uses unsigned numeric types for non-negative quantities. This library uses signed types for values that may be involved in arithmetic operations, so we can lean on UBSan for overflow detection. For a concrete example, compare display::Frame with its associated fuchsia.hardware.display.types/Frame FIDL type.

  • No comparison or arithmetics operators. As a minimum bar, this library overloads == and != for all the types it defines. This makes it easy to use the types in googletest assertions.

  • FIDL currently lacks newtype support for non-composite types (numeric and boolean), and the recommended workaround is struct wrappers. This library offers fbl::StrongInt-based types for internal representation, together with conversion helpers for FIDL’s struct wrappers. This is especially useful for the Display stack, which makes extensive use of 64-bit integers as handles for various resources. For a concrete example, compare display::DisplayId with the fuchsia.hardware.display.types/DisplayId FIDL type.

  • Generated binding for FIDL types containing tables or unions require arena allocations.