What is the difference between an SDL physical key code and an SDL virtual key code?

Question

The struct SDL_Keysym has SDL_Scancode and SDL_Keycode members. What is the difference between them? The documentation does not really clear it up for me. I tried both and they seem to do the same thing.

Answer 1

See the SDL documentation. Scancodes represent the physical position of the keys, modeled after a standard QWERTY keyboard, while Keycodes are the character obtained by pressing the key.

On an AZERTY keyboard, pressing A will emit a 'Q' scancode and an 'a' keycode.

Answer 2

Generally, scancodes are the true values emitted by the keyboard (hardware) to the OS while keycode is what the OS/library maps it to based on the chosen layout. The layout decides the mapping between scancode to some virtual key code. It is part of the operating system's settings. Here, by layout, I mean the functional layout; there're also mechanical and visual layouts. Read more about keyboard layouts in Wikipedia. The concept of scan code and virtual key is explained better with illustration in MSDN.

However, SDL uses scancode to mean something different: the scancode of the key in the US QWERTY keyboard whose location is the same as the one in question. It's the device-independant way of denoting a key based on its location. This is buried in an unusual location in SDL's manual:

Scancodes are meant to be layout-independent. Think of this as "the user pressed the Q key as it would be on a US QWERTY keyboard" regardless of whether this is actually a European keyboard or a Dvorak keyboard or whatever. The scancode is always the same key position.

Keycodes are meant to be layout-dependent. Think of this as "the user pressed the key that is labelled 'Q' on a specific keyboard."

In example, if you pressed the key that's two keys to the right of CAPS LOCK on a US QWERTY keyboard, it'll report a scancode of SDL_SCANCODE_S and a keycode of SDLK_S. The same key on a Dvorak keyboard, will report a scancode of SDL_SCANCODE_S and a keycode of SDLK_O.

In the above quote, by layout the manual means the functional layout. The main part of the manual regarding keyboards is a bit brief on this issue:

SDL_Scancode values are used to represent the physical location of a keyboard key on the keyboard.

SDL_Keycode values are mapped to the current layout of the keyboard and correlate to an SDL_Scancode.

Which one to use is left to the application: scancodes are suited in situations where controls are layout-dependent (eg. the "WASD" keys as left-handed arrow keys), whereas keycodes are better suited to situations where controls are character-dependent (eg. the "I" key for Inventory).

In the above quote, by layout the manual means the mechanical/physical layout. So for controlling the character, for instance, using the scancode is better, while for receiving the user's name keycode is better.