To Propagate Pixel Aspect Ratio from GstCaps to HAL and expose new setPixelAspectRatio() API

[shafi12]

Problem/Opportunity

The video decoder currently derives the Pixel Aspect Ratio (PAR) from the input GstCaps (for example, via the pixel-aspect-ratio field). However, this information is not propagated to the HAL layer.
As a result, downstream components do not have reliable knowledge of the stream’s pixel aspect ratio, even though this information is required to correctly populate the following metadata fields in the HAL:
C++/** * Pixel aspect ratio (PAR) defined as the ratio parX:parY. * e.g. 1:1 for square pixels, 480i=10:11, 576i=59:54 * @see Rec.601 and https://en.wikipedia.org/wiki/Pixel_aspect_ratio */int parX;int parY;Show more lines
This limitation prevents accurate handling of non‑square pixel formats (e.g. legacy SD content) and can lead to incorrect display aspect ratio (DAR) calculations in the downstream video pipeline.

Proposed Solution

1. Add a new HAL API
   Introduce an explicit API to pass pixel aspect ratio hints to the HAL before decoding begins, similar in spirit to setFrameRate().
   Proposed API
   /**

• Sets the pixel aspect ratio (PAR) hint before decoding begins.
• Provides the pixel aspect ratio as a rational number (parX/parY)
• sourced from container metadata or GstCaps (pixel-aspect-ratio).
• This allows the decoder and downstream pipeline (HAL / display)
• to correctly derive the Display Aspect Ratio (DAR).
• Examples:
• • Square pixels : 1/1
• • NTSC 480i (Rec.601) : 10/11
• • PAL 576i (Rec.601) : 59/54
• If the pixel aspect ratio is unknown or not present, callers should
• pass 0/0.
• @PARAM[in] parX Pixel aspect ratio numerator. Must be >= 0.
• @PARAM[in] parY Pixel aspect ratio denominator. Must be > 0 unless parX is 0.
• @exception binder::Status::Exception::EX_NONE

•        Successful completion.
  

• @exception binder::Status::Exception::EX_ILLEGAL_STATE

•        If the resource is not in the READY state.
  

• @exception binder::Status::Exception::EX_ILLEGAL_ARGUMENT

•        If parY is 0 and parX is non-zero.
  

• @pre The resource must be in State::READY.
• @see FrameMetadata.parX, FrameMetadata.parY
  */
  void setPixelAspectRatio(in int parX, in int parY);

Acceptance Criteria (Optional)

No response

Additional Notes (Optional)

No response

[Ulrond]

Design is sound — mirrors setFrameRate() exactly (signature shape, 0/0 = unknown convention, READY-only precondition, exception set), so it slots cleanly into the existing pattern. The proposal also lines up with the existing FrameMetadata.parX / parY output fields — same semantics, just on the input/hint side.

Two implementation details worth nailing down before this lands so vendors don't drift:

1. Hint vs bitstream-derived precedence. When the decoder later finds an explicit PAR in the bitstream (H.264/HEVC VUI aspect_ratio_info_present_flag), does that override the hint, or does the hint take precedence? setStreamResolution() already says "the decoder will use the actual coded dimensions from the bitstream once decoding starts. If those differ, FrameMetadata.codedWidth/codedHeight reflects the true decoded dimensions" — same model would make sense here: bitstream wins, hint is a fallback for streams that don't carry it (legacy SD content, some MPEG-2 etc.).

2. Persistence across flush(). Same question for setFrameRate() — currently silent. Worth declaring once for both setters: hints persist across flush() (they describe the stream, not the playback session) and are cleared only on close(). Otherwise middleware has to re-set them after every flush.

Status

• API genuinely missing — no commit history mentions PAR / aspect ratio / setPixelAspectRatio.
• Issue To Propagate Pixel Aspect Ratio from GstCaps to HAL and expose new setPixelAspectRatio() API #432 was the original tracking issue but got converted into this discussion, so there's no active issue queueing the work.

Happy to raise a tracking issue and implement once the two points above are clarified.

[Ulrond]

Implementation up for review: PR #487 (tracking issue: #486).

The two open design questions raised earlier are baked into the Doxygen:

1. Bitstream wins, hint is fallback. Applied to setPixelAspectRatio() and explicitly added to the existing setColorimetry, setMasteringDisplayInfo, setContentLightLevel, setFrameRate, setDolbyVisionLayerFlags — they were silent on this before. setStreamResolution() already documented it; the others now match.

2. Hints persist across flush(), cleared on close(). Same — applied to all 7 setters.

Plus a new "Stream Hints vs Bitstream Truth" section in video_decoder.md covering precedence, persistence, state precondition, and behaviour under SVP / encrypted pipeline (in-band SEI under SVP is decoder-only territory — cross-links #367 for the broader secure-parser conversation).

If anyone has objections to either decision, the PR is the place to push back.