Video

The Pocket is very particular about how you provide video information. As such, this is likely to be your first stumbling block.

• APF Video Docs

Important Checks

• vsync and hsync must take exactly one cycle
• hsync must come at least 3 cycles after vsync
• video_de should be high only for the pixels you have specified in video.json (unless you're using video_skip as well). Any extra pixels may produce garbled video (though not always)
• vidout_rgb should be set to 0 when video_de is not asserted. The 24-bit value preceeding the first clock in the frame with video_de asserted and the value following the last clock with video_de asserted are both used to configure the scaler. Not zeroing out videout_rgb can have unexpected results

Pocket Video Specifications

Spec	Value
Resolution	16 x 16 up to 800 x 720 pixels
Refresh Rate	47 Hz up to ~62 Hz
Internal Color Format	24-bit RGB8881
Pixel Clock	1MHz to ~50MHz

1: Neither the Pocket internal display nor the Dock displays full 24-bit color. The internal display outputs RGB565 color, and the Dock outputs 21-bit color

Signal Generation

Visit https://tomverbeure.github.io/video_timings_calculator and enter your desired horizontal and vertical pixel counts. These numbers should help you determine what clock speed you want to use.

The APF scaler requires two clocks, your main video clock, and an additional clock of the same frequency but 90 degrees out of phase with the main clock (most likely you will not use this clock yourself). However you determine your pixel clock, make sure:

• the resulting time for each frame is between 47 and 61hz
• your image size is between 16x16 and 800x720 pixels

Note that smaller resolutions (in my case 128x64) may produce some unusual scaling results that drop pixels to provide a nice scaling. If this is not desirable, try integer scaling the video yourself and positioning it on the screen (see my Arduboy port).

Pixel Clock Considerations

• The video clock of the original hardware is not necessarily what you want for APF
  • APF wants exactly one clock per pixel
• Given you are likely not clocking your core off of the APF video clock, regardless of what clock you provide to APF, the vsync and hsync timing will remain constant
  • Specifically, there is a fixed number of hsync for every frame (each vsync), this is the number of rows of lines, and is your vertical resolution that you should set in video.json
• Therefore, your pixel clock should be chosen to provide exactly the right number of clocks per pixel in the horizontal, while providing ~60Hz per vsync

Generic Video Explanation

Blanking

APF does not require accurate blanking times, and in fact should be able to consume pixels immediately after hsync goes low. However, for clarity of how video works in general, CRT (and therefore standard video signal) blanking works as follows:

Image from Stack Exchange

• vblank period
  • Front porch - We've stopped drawing lines, about to move to the top of the screen
  • vsync - We're about to start drawing this frame
  • Back porch - Period the electron beam is moving back to the top of the screen. Additionally, the electron beam may begin to draw lines, but these are likely to be black (or garbage) and off of the top of the screen
  • Frame content: hblank to follow
• hblank period
  • Front porch - We've stopped drawing this scanline, and we're about to move to the next one
  • hsync - We're about to start drawing this scanline
  • Back porch - Period the electron beam is moving back to the left of the screen after drawing a scanline
  • Scanline begins: hblank to follow
  • After all scanlines, we once again enter vblank

Image from Designing Video Game Hardware in Verilog by Hugg

See also

Troubleshooting

Make sure you have first verified that you followed Important Checks above.

• You do not need accurate porch alignment. Once the requirements of vsync and hsync are met, you can throw pixels up whenever. In fact, you don't need a porch at all, and can output pixels immediately after hsync
  • This doesn't mean you won't get "glitchy" video (pixels don't fit on the screen, pixels overrun the screen and cause the columns to be messed up, no video at all), but you will get a green Sync indicator with Statistics turned on in Tools
• You do not need accurate video.json. As above, this will just mean misaligned pixels
• If you have the appropriate hardware, inspect the sync signals coming out of the core with SignalTap
  • Some older arcade cores actually have vsync come in the middle of an hsync signal. As of writing (firmware 1.1-beta-3) this can hard crash the scaler, to the point that no core will produce video. If you suspect this occurs, you must fully restart your Pocket before video will work again