Skip to content

Reference Guide

IanSB edited this page Nov 11, 2020 · 69 revisions

Home

⚠️ Under Construction

Main Menu

This is the initial menu displayed when the menu button is pressed and can be used to setup RGBtoHDMI for first use and to select all the other menu options

Info Menu

This menu allows various information to be displayed and also allows rebooting and programming of the CPLD.

Source Summary

Displays technical information about the video source and the Pi's frame buffer.

System Summary

Displays technical information about the system including CPLD version and Pi clocks etc.

Calibration Summary

Displays current calibration summary

Calibration Detail

Displays current calibration detail if available

Calibration Raw

Displays current calibration raw data if available

Credits

Displays credits

Reboot

Selecting will reboot the Pi.
Useful if the hat is plugged into a Pi which doesn't have the reset header fitted or available

Palette Menu

Sets palette preferences

Palette

Selects which palette is use to display the current computer e.g RGB RGBI RrGgBb etc.

Output Colour

Values: Normal / Monochrome / Green / Amber

Changes the output to simulate a monochrome, green or amber monitor.

Output Invert

Values: Normal / RGB/YUV / G/Y

Inverts either all three RGB/YUV video signals or just the Green/Y signal.

Border Colour

Values: 0-255

Changes the border colour (the area of the screen not being written to by the capture code).
Values of 128-255 fill the whole screen and this is used for the colour test profile.

Brightness

Contrast

Gamma

Saturation

Tint

All the above allow the output image to be adjusted

Palette Control

Values: Off / In Band Commands / CGA NTSC Artifact / Mono NTSC Artifact / Auto NTSC Artifact / PAL Artifact / Atari GTIA

In Band Commands allows the computer to reprogram the palette by sending special pixel combinations.

NTSC Artifacting simulates the false colour effects used on NTSC systems to generate colour from a monochrome source.
The Auto option detects the colour burst to turn artifacting on and off.

PAL Artifact - not implemented yet

Atari GTIA - decodes 256 Atari colours from c0pperdragons's YUV converter

The above options are still under development.

NTSC Artifact Colour

Values: On / Off

Manually turns NTSC artifacting on and off

Colour Phase

Values: 0-3

Selects which NTSC quadrant the artifact colours use. This should be adjusted until the artifact colours look correct.

Preferences Menu

Sets user preferences

Scanlines

Values: Off / On

Turns scanlines on and off.
NOTE Scanlines will not be visible when the menu is on screen.

Scanline Level

Sets the intensity of the scanlines.
0 = black, 15 = very slightly dimmed compared to the non-scanlines.

Values: 0-15

Teletext Deinterlace

Values:

  • None
  • Simple Bob
  • Simple Motion 1
  • Simple Motion 2
  • Simple Motion 3
  • Simple Motion 4
  • Advanced Motion

Determines the algorithm used to deinterlace teletext displays such as the BBC micro's mode 7.
Simple Bob used the "bob" algorithm which introduces vertical shimmer.
Simple Motion uses 25Hz motion detection and the level determines the tradeoff between weaving and fizzing artifacts (1 = most "weave", least "fizz", 4 = least weave, most "fizz").
Advanced Motion should be used for best results and has no weave at all with minimal "fizz". The other options are only required for earlier CPLD versions prior to v3.0.

Normal Deinterlace

Values: None (Weave) / Simple BoB

Selects the deinterlacing technique for non-teletext interlaced sources

Teletext Scaling

Values: Even / Uneven (3:2>>4:3)

Converts a 3:2 teletext image to 4:3.
When using integer scaling, the BBC's mode 0 will normally fit on the screen with a 4:3 image but due to the different (12Mhz) pixel clock of teletext it will fit onto the screen with a 3:2 aspect ratio.
Enabling the "Uneven (3:2>>4:3)" will squash the horizontal resolution of teletext so that it has a 4:3 aspect ratio to match the other modes.
When using "Integer/sharp" scaling this can result in some unevenness in teletext characters.

Normal Scaling

Values: Even / Uneven (3:2>>4:3)

Converts a 3:2 progressive image to 4:3
Same as Teletext Scaling but for non-teletext modes.
This option will only have an effect on 3:2 screens and is generally only useful for the Camputers lynx and Oric which have 6 Mhz pixel clocks.

Swap Aspect 625<>525

Values: Off / On

When enabled, it makes some PAL sources output with an NTSC aspect ratio and vice-versa

Crop Border

Values: 0% to 100%

Crops the size of the capture area.

0% = no cropping 100% = crop to the minimum size from the geometry menu

With "Integer" scaling, this simply crops off the excessive border but leaves the scaling unchanged.
With "Interpolated" scaling, the border area is cropped off and the new cropped area is scaled to fill the screen so it acts like a zoom function.

ScreenCap Size

Values: Normal / Full Screen / 4:3 Crop / Full 4:3 Crop

The Pi can capture a frame of the displayed video and write it to the SD card as a PNG file and this setting controls the size and shape of the screencap:
Normal - captures with screen aspect ratio usually at half size
Full Screen - captures with screen aspect ratio at full screen size
4:3 Crop - captures with 4:3 aspect ratio usually at half size
Full 4:3 Crop - captures with 4:3 aspect ratio at full screen size

Settings Menu

Adjusts setting that are generally left unchanged

Font Size

Values: Always 8x8 / Auto 12x20 4bpp / Auto 12x20 8bpp

There are two fonts used by the software, a small 8x8 and a larger 12x20.
Always 8x8 will always use the 8x8 font.
Auto 12x20 4bpp will use the 12x20 font in 4bits per pixel modes but switch to the 8x8 font if the text won't fit on the screen. In 8 bits per pixel mode the 8x8 font is always used.
Auto 12x20 8bpp will use the 12x20 font in both 4 and 8 bits per pixel modes but switch to the 8x8 font if the text won't fit on the screen.

V Sync Indicator

Values: Off / On

Turns on a red bar which shows the phase relationship between the input video signal and the Pi's video output. If the bar is not moving it means the two are locked together.

Genlock Mode

Values: On (Locked) / Off (Unlocked)

On (Locked) means the Pi's video output is locked to the source video. This is the normal mode of operation and is used to keep the video in sync and prevent tearing or glitching of the video signal. It also means the lag (delay between input and output) can be kept to around 3 milliseconds because once genlocked, the phase relationship is arranged so that the Pi reads the video out of the frame buffer almost immediately after it has been written by the capture code.

Off (Unlocked) means the Pi runs independantly of the video source. This will result in tearing unless the number of buffers is increased to 3 or more which will significanly increase lag.

The led next to SW1 on the board indicates the genlock state:
Off = Unlocked
Flashing = Locking in progress
On = Locked

Periodically the Pi will need to re-lock to the source and this is indicated by brief flashing of the led.

If the led continues flashing it means the Pi can't lock to the source which is usually due to the input frame rate not being the same as the Pi's output frame rate.

Genlock Line

Values: 35-140

This sets the position of the red bar and this should generally be towards the top of the screen to minimise lag.

Genlock Speed

Values: Slow (333PPM) / Medium (1000PPM) / Fast (2000PPM)

Controls the rate at which the Pi locks to the video source.
If your monitor blanks briefly during genlocking (when the led is flashing) then try reducing the genlock speed.

Genlock Adjust

Values: -5% to +5% / Full Range

Controls the maximum adjustment of the Pi's video output when genlocking.

-5% to +5% limits the adjustment range to those values.
e.g. if the Pi is set to 50hz output it will only adjust between 47.5Hz and 52.5Hz so if the source is 60Hz it will never lock and you will get a warning on the menu status line. (In such a case the Pi's video output should be switched to 60Hz)

Full Range allows the Pi to lock to any frequency so it would change the 50Hz to 60Hz. This option is not normally recommended as it can result in very non-standard video outputs that the monitor will be unable to display.

Num Buffers

Values: 1 to 4

Controls the number of frame buffers used to buffer the video signal. Settings 2 to 4 add 1 to 3 frames of lag respectively to the output.
The default is 1 and it is only useful to use other options to prevent tearing if genlock is disabled.

Return Position

Values: Start / End

Sets the position of the Return menu option to the start or end of each menu.

TODO: We should drop this from the OSD, as it gets save per-profile wich is very confusing

Overclock CPU

Overclocks the CPU in Mhz

Overclock Core

Overclocks the Core in Mhz (This is the only setting that usually makes any difference as it speeds up GPIO reads)

Overclock SDRAM

Overclocks the SDRAM in Mhz

Debug

Switches on vertical lines in the video capture area, used to check alignment.

Geometry Menu

Sets the capture area sampling size, clock and sync etc.

Setup Mode

Values: Normal / Set Min/Offset / Set Maximum / Set Clock/Line / Fine Set Clock

This setting makes it easier to setup the associated values below.
When setting the offset and minimum values, select "Set Min/Offset" which reduces the capture area to the minimum values and you can adjust these 4 values so that exactly the screen output of the source is captured.

Similarly select "Set Maximum" before adjusting the maximum values as this forces the capture area to the maximum values

Select "Set Clock/Line" when setting the clock and line values as this disables the clock tolerance which is required when making clock and line adjustments. The clock is adjusted in 1000Hz increments

Finally "Fine Set Clock" changes the clock increment to 1

This setting is automatically returned to "Normal" when you leave the geometry menu.

H Offset

Values: 0-512

Controls the horizontal position of the capture area

V Offset

Values: 0-512

Controls the vertical position of the capture area

Min H Width

Values: 100-1920

Sets the minimum number of horizontal pixels to capture. This is normally set to the number of pixels output by the source computer at it's highest resolution.
e.g. for a BBC micro this would be 640.

Min V Height

Values: 100-1200

Sets the minimum number of vertical pixels to capture. This is normally set to the number of pixels output by the source computer at it's highest resolution.
e.g. for a BBC micro this would be 256.

Max H Width

Values: 150-1920

Sets the maximum number of horizontal pixels to capture. This is normally set to a larger value that covers the border area and that usually results in a 4:3 ratio with the max vertical height for square pixels or 8:3 ratio with 1:2 pixels like the BBC micro.
e.g. for a BBC micro this would be 768.

Max V Height

Values: 150-1200

Sets the maximum number of vertical pixels to capture. This is normally set to a larger value that covers the border area and that usually results in a 4:3 ratio with the max horizontal width for square pixels or 8:3 ratio with 1:2 pixels like the BBC micro.
e.g. for a BBC micro this would be 288 (768x288 = 8:3).

H Pixel Aspect

Values: 0-8

Sets the horizontal pixel aspect ratio (not the screen aspect ratio)
This is used to determine the integer scaling ratio. If it is set to 0, integer scaling will try to fill as much of the screen as possible without maintaining a fixed aspect ratio.
e.g. for a BBC micro this would be set to 1 (1:2 aspect pixels)
When you adjust this value some helper info is displayed on the status line

V Pixel Aspect

Values: 0-8

Sets the vertical pixel aspect ratio (not the screen aspect ratio)
This is used to determine the integer scaling ratio. If it is set to 0, integer scaling will try to fill as much of the screen as possible without maintaining a fixed aspect ratio.
e.g. for a BBC micro this would be set to 2 (1:2 aspect pixels)
When you adjust this value some helper info is displayed on the status line

FB Size

Values: Normal / Double Height / Double Width / Double Width+Height

The frame buffer is normally set to a value between the minimum and maximum values above but sometimes it is useful to double the size of the frame buffer vertically, horizontally or both as that can improve the quality of the scaled output. Setting this option doubles the size of the buffer in the appropriate direction.
e.g the BBC micro with 640x256 uses the double height option for a frame buffer of 640x512. Smaller resolutions like the Atom or Spectrum should used both.
Also if you want to use scanlines then Double Height must always be enabled.

FB Bits/Pixel

Values: 4 / 8 / 16

Sets the frame buffer to use 4, 8 or 16 bits per pixel. If you are capturing 12 bits per pixel this should be set to either 8 or 16 bits per pixel. If you are capturing 6 bits per pixel this should always be set to 8 bits per pixel. If you are capturing 3 bits per pixel this can be set to 4 or 8 bits per pixel.

Clock Frequency

Values: 1000000 - 40000000

i.e. 1MHz to 40MHz

Sets the pixel clock frequency used to sample the incoming video.
Starting to adjust this value automatically sets the setup mode to "Set Clock/Line"
When you adjust this value some helper info is displayed on the status line

Line Length

Values: 100-5000

Sets the number of clock cycles per video line on the incoming video.
Starting to adjust this value automatically sets the setup mode to "Set Clock/Line"
When you adjust this value some helper info is displayed on the status line

Clock Tolerance

Values: 0-100000

Sets the range of adjustment in PPM of the above clock frequency when locking to the incoming video.
If the adjusted clock is outside this range then the previous frequency or default frequency is used. This allows software that creates non-standard video timings to work. Normally in the range 4500 - 25000 depending on the source.
When you adjust this value some helper info is displayed on the status line

Lines per Frame

Values: 250-1200

Sets the number of lines per field/frame of the incoming source.
e.g. 312 for PAL 50 Hz sources
When you adjust this value some helper info is displayed on the status line

Sync Type

Values: -H-V / +H-V / -H+V / +H+V / Composite / Inverted

Sets the sync type and polarity of the incoming video source

Vsync Type

Values: Auto / Interlaced / Interlaced 160uS Vsync / Non Interlaced / Flywheel

Sets the vertical sync type used by the source.
Auto will switch between the two interlaced types The Flywheel setting should be used when vertical sync pulses are generated by RC time constants.
e.g. UK101, Superboard, TRS80

Video Type

Values: Progressive / Interlaced / Interlaced Teletext

Sets the type of video used by the source. Most sources are progressive except for teletext which uses interlaced video.

Pixel Sampling

(OLD CPLDs ONLY) Values: Normal / Odd / Even / Half Odd / Half Even

This option is not shown in the menu with latest CPLDs and is used by old CPLDs to sample lower resolution sources like the Atom

Sampling Menu (3 BIT & 6 BIT TTL digital inputs)

This menu varies when used with a BBC micro depending on the video mode.

In mode 7 the following options are available:

In other BBC modes and with all other supported computers the following options are displayed:

Setup Mode

Values: Normal / Set Delay

This setting makes it easier to setup the Delay value.
Selecting "Set Delay" reduces the capture area to the minimum values and you can adjust the delay value so that the video exactly lines up with the capture area.

This setting is automatically returned to "Normal" when you leave the sampling menu.

Sampling Phase

Values: 0-X

This adjusts the video sampling point and it can be changed to eliminate any noise in the video signal. This value is automatically set by using the "Auto Calibrate Video Sampling" option in the main menu or using the shortcut calibration on the one of the buttons. The range depends on the Clock Multiplier setting below.

A-F Phase

Values 0-7

These offsets are available in BBC mode 7 teletext only and can be used to fine adjust the sampling when used with the non-symmetrical 12 Mhz pixel clock used in that mode.

Half Pixel Shift

Values: Off / On

This setting adds an additional sampling delay of half a pixel. It is set as required during Mode 7 auto calibration if the optimal sampling point is at one extreme of the range. For example, if the sampling point is 0-1 or 6-7, then this setting will be enabled to shift the sampling point to 2-5 (i.e. in the middle of the range). This gives scope for incremental adjustment of the individial A-F sampling offsets, without any risk of them reaching the limits.

Clock Multiplier

With the BBC CPLD:
Values: x6, x8, x12, x16

With the RGB CPLD:
Values: x3, x4, x6, x8, x10, x12, x14, x16

The pixel clock is multipled by the above values to set the master sampling clock.
This also changes the range of sampling offsets which will be from 0 to one less than the multiplier value.
Increasing the multiplier increases the sampling accuracy and reduces jitter but setting it to too high a value will overclock the CPLD and cause it to malfunction. Generally the the value of the pixel clock times the multiplier value should be kept below around 150Mhz.

Delay

Values: 0 to 15

Adjusts the fine horizontal position of the capture area that has been set in the Geometry menu.
When used with a BBC micro this value is set automatically as part of the "Auto Calibrate Video Sampling" option.

Sample Mode

Values: 3 Bits Per Pixel / 6 Bits Per Pixel / 9 Bits (V sync) / 9 Bits (Bits 0-2) / 9 Bits (Bits 1-3) / 12 Bits per pixel / 6x2 Mux (12BPP) / 6 Bits (4 Level) / 1 Bit Per Pixel

Changes the type of sampling:
3 Bits Per Pixel = 3 Bit sampling.
6 Bits Per Pixel = 6 Bit sampling.
9 Bits (V sync) = 9 Bit sampling but the ninth bit uses the Vsync input so only requires the standard 8 bit header
9 Bits (Bits 0-2) = 9 bit sampling using bits 0-2 with bit 3 unused for each of RGB
9 Bits (Bits 1-3) = 9 bit sampling using bits 1-3 with bit 0 unused for each of RGB
12 Bits per pixel = 12 bit sampling
6x2 Mux (12BPP) = 12 bit sampling by multiplexing the 12 bits at double rate on the 6 bit input
6 Bits (4 level) = use 3 line to 2 bit encoders on the analog card to increase the number of analog levels detected.
1 Bit per pixel = 1 bit sampling

Input Mux

Values: Off / On

In the 3 BIT board when set to on, a TTL buffer chip is switched into the RGB input path to change the logic thresholds from CMOS to TTL which improves logic level detection with some computers such as the Electron although it is not essential.

Sync on G/V

In the 6 BIT board when set to on, sync is sourced from the Vsync input rather than the normal sync input. This is primarily to support sync on green with the analog board.

Sampling Menu (6 BIT RGB analog inputs)

When the analog addon board is fitted, the following additional "DAC" menu options are displayed: The DACs are used to set the thresholds for comparators which allow 3 levels of RGB to be discriminated

Input Coupling:

Values DC/High Impedance / AC/High Impedance / DC/75R Termination / AC/75R Termination

Changes the way the analog input is handled:
DC/High Impedance = the G signal is DC coupled and all RGB inputs are high impedance.
AC/High Impedance = the G signal is AC coupled via a capacitor and clamp circuit. All RGB inputs are high impedance.
DC/75R Termination = the G signal is DC coupled and all RGB inputs are 75 Ohm terminated.
AC/75R Termination = the G signal is AC coupled via a capacitor and clamp circuit. All RGB inputs are 75 Ohm terminated.
Note the R and B signals are always DC coupled.

Generally, only the DC modes should be used with RGB signals as the AC option is primarily for use with YUV sources.
If AC coupling is selected, the DAC-G setting will have to be adjusted appropriately.

DAC-A: G Hi

Values: 0 to 255

Sets the voltage of the highest green level above black

DAC-B: G Lo

Values: 0 to 255

Sets the voltage of the lowest green level above black

DAC-C: RB Hi

Values: 0 to 255

Sets the voltage of the highest red and blue levels above black

DAC-D: RB Lo

Values: 0 to 255

Sets the voltage of the lowest red and blue levels above black

DAC-E: G/V Sync

Values: 0 to 255

Sets the voltage of the Vsync input which is also connected to the green signal.
If Input Mux is set to "on" (see above) this can be used to detect sync on green.

DAC-F: Sync

Values: 0 to 255

Sets the voltage threshold of the sync input

DAC-G: G Clamp

Values: 0 to 255

The G input is clamped using sync tip clamping in AC coupling mode and this sets the clamping voltage level.
For RGB inputs, this is normally set to 0

Sampling Menu (6 BIT YUV analog inputs)

When the the CPLD reprogrammed to the YUV version, the following menu options are displayed:

The DACs below are used to set the thresholds for comparators which allow 3 levels of YUV to be discriminated.

Setup Mode

Values: Normal / Set Delay

This setting makes it easier to setup the Delay value.
Selecting "Set Delay" reduces the capture area to the minimum values and you can adjust the delay value so that the video exactly lines up with the capture area.

This setting is automatically returned to "Normal" when you leave the sampling menu.

Offset

Values: 0-15

This adjusts the video sampling point and it can be changed to eliminate any noise in the video signal. This value is automatically set by using the "Auto Calibrate Video Sampling" option in the main menu or using the shortcut calibration on the one of the buttons.

Filter Y

Values: Off /On

Enables noise filtering in the Y channel

Filter UV

Values: Off / On

Enables noise filtering in the U & V channels

Subsample UV

Values: Off / On

Halves the sample rate on the U and V channels (Used on 6847 sources)

Pal Switch

Values: Off / On

Inverts the V (R-Y) signal on alternate lines (Required by 48K Spectrum input)

Sync Edge

Values Trailing / Leading

Sets whether sync timing is taken from the Trailing or Leading edge of the sync pulse This should normally be set to "Trailing" and only set to "Leading" if there is a problem with the trailing edge of the sync pulse. "Leading" is currently only used by UK101, Superboard and Spectrum 48K

Clamp Type

Values Sync Tip / Back Porch Short / Back Porch Medium / Back Porch Long / Back Porch Auto

Switches the type of clamping from sync tip to back porch. Sync Tip Clamping clamps the incoming Y signal to the bottom of the sync pulse Back Porch Clamping clamps the incoming Y signal to the back porch level.
The Auto option automatically selects the right length of back porch for the current sample clock.

Delay

Values: 0 to 15

Adjusts the fine horizontal position of the capture area that has been set in the Geometry menu.

Input Mux

Values: Off / On

Used to change the behaviour of the DAC-E: Y/V Sync setting (see below)

Input Coupling:

Values DC/High Impedance / AC/High Impedance / DC/75R Termination / AC/75R Termination

Changes the way the analog input is handled:
DC/High Impedance = the Y signal is DC coupled and all YUV inputs are high impedance.
AC/High Impedance = the Y signal is AC coupled via a capacitor and clamp circuit. All YUV inputs are high impedance.
DC/75R Termination = the Y signal is DC coupled and all YUV inputs are 75 Ohm terminated.
AC/75R Termination = the Y signal is AC coupled via a capacitor and clamp circuit. All YUV inputs are 75 Ohm terminated.
Note the U and V signals are always DC coupled.

If AC coupling is selected, the Clamp type and DAC-G settings will have to be adjusted appropriately.

DAC-A: Y Hi

Values: 0 to 255

Sets the voltage of the highest Y level above black

DAC-B: Y Lo

Values: 0 to 255

Sets the voltage of the lowest Y level above black

DAC-C: UV Hi

Values: 0 to 255

Sets the voltage of the highest U and V levels

DAC-D: UV Lo

Values: 0 to 255

Sets the voltage of the lowest U and V levels

DAC-E: Y/V Sync

Values: 0 to 255

Sets the voltage of the Vsync input which is also connected to the Y signal.
When Input Mux is set to off, this is used to discriminate the Vsync signal on 6847 sources.
When Input Mux is set to on, this switches the Y input from 3 levels to 4 levels and the value is used to set the threshold for the middle Y level.

DAC-F: Sync

Values: 0 to 255

Sets the voltage threshold of the sync input

DAC-G: Y Clamp

Values: 0 to 255

The Y input is clamped using sync tip clamping or back porch clamping in AC coupling mode and this sets the clamping voltage level

Sampling Menu (Atom)

Offset

Values: 0-15

This adjusts the video sampling point and it can be changed to eliminate any noise in the video signal. This value is automatically set by using the "Auto Calibrate Video Sampling" option in the main menu or using the shortcut calibration on the one of the buttons.

Filter Y

Values: Off / On

Enables noise filtering in the Y channel

Filter UV

Values: Off / On

Enables noise filtering in the U & V channels

Update CPLD Menu

Allows the CPLD to be reprogrammed

Clone this wiki locally