NAME
	/dut/dvi-video.nut

DESCRIPTION
	Playing the dvi-video.nut file streams video from the DUT:

		[harness]<----(DVI-D)----<[DUT]
		         ^
		         |
		  HDMI-style socket

	The socket on the harness is single-link DVI-D using an
	HDMI-style physical receptacle.  Because HDMI is backwards
	compatible with DVI-D, the harness is able to receive video
	from both DVI-D-compliant DUTs and from HDMI-compliant DUTs;
	though the harness itself is **not** HDMI-compliant.

	The harness emits the video in the NUT container format; while
	somewhat obscure, NUT is supported by most video players and
	should "just work" (being well-supported by FFmpeg, which
	essentially everything uses under the hood).

	The following resolutions are supported:

	- 640x480p @ 59.94/60Hz
	- 720x480p @ 59.94/60Hz
	- 720x576p @ 50Hz

	While input is read from the DVI-D socket at 50/59.95/60 FPS,
	if dvi-video.nut is not read that fast, then frames are
	silently dropped.  Reading dvi-video.nut at full frame-rate
	means reading at ~82.95 Mbps for 50 FPS or ~99.54 Mbps for 60
	FPS.

BUGS
	- The video's color-depth is reduced from 24bpp RGB to to 8bpp
	  RGB, and the video is downscaled horizontally by half.  The
	  downscaling algorithm is particularly bad; simply skipping
	  every-other pixel.

	- Because reading of frames is virtually guaranteed to not be
	  aligned with the ingestion of frames, "tearing" will occur.

	- No matter the resolution received, dvi-video.nut will be
	  720x576, and will "letterbox" lower resolutions.

	- The Ethernet interface on the harness is not actually
	  capable of the speeds required to avoid dropping frames.

COMPATIBILITY
	- `ffplay` does not handle non-square pixels; because of the
	  horizontal downscaling, the displayed image will be too
	  narrow by half.

	- When displaying the video, `mpv`/libplacebo make some
	  invalid assumptions about divisibility of framebuffers sizes
	  and GPU texture sizes (and our 360 pixel-wide framebuffers
	  seem to trip this); the default `--vo=gpu` may fail to
	  display the video; this can be worked around
	  with`--vo={anything_else}`.

RATIONALE
	Though the harness has an HDMI-style connector, it only
	supports DVI-D.  If it's DVI, why use this connector instead
	of a "more honest" DVI connector?  Two reasons:

	- We anticipate that most DUTs that our users will want to
	  plug into it have HDMI ports, and that our users are more
	  likely to already have an HDMI cable than an HDMI←→DVI cable
	  or HDMI←→DVI adapters.  We also anticipate that users who
	  actually do have DUTs with DVI ports *do* already have
	  DVI←→HDMI adapters.

	- HDMI-style sockets are much cheaper than DVI sockets; using
	  a DVI socket would have increased the cost of the harness by
	  several dollars.

AUTHOR
	Copyright (C) 2025  Luke T. Shumaker <lukeshu@lukeshu.com>
	SPDX-License-Identifier: AGPL-3.0-or-later