[Feature Request] Add RETRO_ENVIRONMENT_GET_DISPLAY_INFO in libretro.h

[rtomasa]

At present, libretro cores can provide video geometry to the frontend via retro_get_system_av_info() and can update it at runtime via RETRO_ENVIRONMENT_SET_GEOMETRY. However, there is currently no frontend-to-core API that allows a core to query the frontend’s effective display or content viewport geometry.

This would be useful in cases where a core needs advisory information about how its output is actually being presented by the frontend. One example is a video player core with a Zoom option: in order to compute an automatic zoom level that fills the screen correctly, the core may need to know the effective display or viewport aspect ratio selected by the frontend. Similar cases can arise in specialized cores whose presentation requirements differ from those of standard emulators.

I would like to propose a new experimental environment callback, tentatively using environment ID 82:

#define RETRO_ENVIRONMENT_GET_DISPLAY_INFO (82 | RETRO_ENVIRONMENT_EXPERIMENTAL)

with a struct along these lines:

struct retro_display_info
{
   uint32_t struct_size;          /* Set by core to sizeof(struct retro_display_info). */
   uint64_t flags;                /* Validity/state flags. */

   unsigned display_width;
   unsigned display_height;

   unsigned viewport_x;
   unsigned viewport_y;
   unsigned viewport_width;
   unsigned viewport_height;

   float display_aspect_ratio;
   float viewport_aspect_ratio;
};

#define RETRO_DISPLAY_INFO_VALID_DISPLAY_SIZE   (1ULL << 0)
#define RETRO_DISPLAY_INFO_VALID_VIEWPORT       (1ULL << 1)
#define RETRO_DISPLAY_INFO_VALID_DISPLAY_AR     (1ULL << 2)
#define RETRO_DISPLAY_INFO_VALID_VIEWPORT_AR    (1ULL << 3)
#define RETRO_DISPLAY_INFO_WINDOWED             (1ULL << 4)
#define RETRO_DISPLAY_INFO_FULLSCREEN           (1ULL << 5)

Example core-side usage:

struct retro_display_info info;
memset(&info, 0, sizeof(info));
info.struct_size = sizeof(info);

if (environ_cb(RETRO_ENVIRONMENT_GET_DISPLAY_INFO, &info))
{
   if (info.flags & RETRO_DISPLAY_INFO_VALID_VIEWPORT_AR)
   {
      float ar = info.viewport_aspect_ratio;
      /* Use advisory effective presentation aspect ratio here. */
   }
   else if ((info.flags & RETRO_DISPLAY_INFO_VALID_VIEWPORT) &&
            info.viewport_height != 0)
   {
      float ar = (float)info.viewport_width / (float)info.viewport_height;
   }
}

Suggested semantics:

• display_width / display_height describe the frontend output surface in physical pixels, when known
• viewport_* describe the final content viewport actually used to present the core image, when known
• display_aspect_ratio is the output surface aspect ratio
• viewport_aspect_ratio is the effective presented content aspect ratio
• any dimension may be 0, and any aspect ratio may be <= 0.0f, when unknown
• the call is advisory only; the frontend remains fully in control of presentation
• frontends may change these values at runtime