ShuriZma
/
RetroArch
mirror of https://github.com/libretro/RetroArch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated Overlay image configuration (markdown)

Hans-Kristian Arntzen 2013-10-21 07:19:04 -07:00
parent 7d9f822e0f
commit 855f9c72ac
1 changed files with 26 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Overlay-image-configuration.md

@ -3,9 +3,9 @@
RetroArch supports overlay images for use with hardware accelerated drivers. RetroArch supports overlay images for use with hardware accelerated drivers.
The purpose of this is to allow some kind of input interface that is mouse/touch oriented. The purpose of this is to allow some kind of input interface that is mouse/touch oriented.
The overlay image is displayed with transparency over the regular game image, and the user is able to trigger input by pressing on certain parts of the overlay. The overlay images are displayed with transparency over the regular game image, and the user is able to trigger input by pressing on certain parts of the overlay.
Since the overlay is an image, the user should be able to fully configure the look and functionality of this overlay. This allows skinners and themers to go wild. Since the overlay is a series of images, the user should be able to fully configure the look and functionality of this overlay. This allows skinners and themers to go wild.
## Configuration ## Configuration
@ -14,20 +14,20 @@ The overlay is described in a config file `*.cfg`. The config file uses the same
The overlay system supports use of multiple overlays that can be switched out on the fly. Input is not only restricted to gamepad input, but can also work with any input that is bindable in RetroArch, e.g. save states, rewind, load state, etc. The overlay system supports use of multiple overlays that can be switched out on the fly. Input is not only restricted to gamepad input, but can also work with any input that is bindable in RetroArch, e.g. save states, rewind, load state, etc.
The config file describes: The config file describes:
- Which overlay images to use (.png, .tga, etc). - Which full-screen overlay images to use (.png, .tga, etc).
- Which coordinates on each overlay correspond to which input event.
- The hitbox for each input event, i.e. "size" of the button. - The hitbox for each input event, i.e. "size" of the button.
- Where on the screen the overlay should be displayed. - Which image should be shown over the input descriptors individually (optional).
- Where on the screen the entire overlay should be displayed.
### Overlay images ### Full-screen overlay images
First we configure how many overlays we use, and where they can be found. First we configure how many overlays we use. Every overlay can have one full-screen overlay, but is optional. The full-screen overlay is supported for compatibility with older format.
overlays = 2 overlays = 2
overlay0_overlay = overlay_img0.png overlay0_overlay = overlay_img0.png # Optional
overlay1_overlay = overlay_img1.png overlay1_overlay = overlay_img1.png # Optional
The paths are relative to where the overlay config is loaded from. If the path is absolute, absolute paths will be used. On Unix-like systems `~/` is recognized as `$HOME`. The paths are relative to where the overlay config is loaded from. If the path is absolute, absolute paths will be used. On Unix-like systems `~/` is recognized as `$HOME/`.
### Screen placement ### Screen placement
@ -46,7 +46,7 @@ The default (stretch to full screen) could be described as such:
overlay0_rect = "0.0,0.0,1.0,1.0" overlay0_rect = "0.0,0.0,1.0,1.0"
### Full-screen overlays ### Full-screen vs. full-viewport overlays
By default, overlays will be stretched out to fill game viewport. However, in some cases By default, overlays will be stretched out to fill game viewport. However, in some cases
the aspect ratio of the game causes there to remain large black borders around the game image. the aspect ratio of the game causes there to remain large black borders around the game image.
@ -68,17 +68,30 @@ The format is:
"button,position_x,position_y,hitbox_type,range_x,range_y" "button,position_x,position_y,hitbox_type,range_x,range_y"
`button` corresponds to the input event being generated. The names are the same as in the general input config, e.g. input_player1_start would translate to start here. overlay_next is a special bind designed to swap to the next overlay, or wrap around to the first one. `button` corresponds to the input event being generated. The names are the same as in the general input config, e.g. input_player1_start would translate to start here. overlay_next is a special bind designed to swap to the next overlay, or wrap around to the first one. Button `nul` means no input.
For an up-to-date view of what buttons are called, check: For an up-to-date view of what buttons are called, check:
https://github.com/Themaister/RetroArch/blob/master/input/input_common.c#L499 https://github.com/Themaister/RetroArch/blob/master/input/input_common.c#L499
`position_x` and `position_y` are the x and y coordinates in pixels of the source image for the center of the button. `position_x` and `position_y` are the x and y coordinates in pixels of the source image for the center of the button. It is possible to use normalized coordinates as well. This is necessary when a full-screen overlay is not used. `overlay0_desc0_normalized = true` will force normalized coordinates. `overlay0_normalized = true` sets all descriptors to true unless overridden specifically.
`hitbox_type` describes which type of shape the button has. `radial` (circle, ellipsis) and `rect` (rectangular) shapes are supported. `hitbox_type` describes which type of shape the button has. `radial` (circle, ellipsis) and `rect` (rectangular) shapes are supported.
`range_x` and `range_y` describe the size of the button. The semantics differ slightly for radial and rect hitbox types. For `radial` shape, `range_x` and `range_y` describe the radius in x and y directions in pixels of the source image. For `rect` shape, the `range_x` and `range_y` values represent the distance from center to the edge of the rect in terms of pixels of the source image. E.g. a `range_x` of 20 would mean the width of the rectangular is 40 pixels in total. `range_x` and `range_y` describe the size of the button. The semantics differ slightly for radial and rect hitbox types. For `radial` shape, `range_x` and `range_y` describe the radius in x and y directions in pixels of the source image. For `rect` shape, the `range_x` and `range_y` values represent the distance from center to the edge of the rect in terms of pixels of the source image. E.g. a `range_x` of 20 would mean the width of the rectangular is 40 pixels in total.
A special type of button is `analog_left` and `analog_right`. These translate to analog sticks. These buttons must have hitbox type `radial`. It is possible to configure where saturation kicks in using `overlay%u_desc%u_saturate_pct`. E.g. a value of 0.75 means the 75% inner part contains the entire analog range. Outside the 75% it will be fully saturated.
### Using per-button overlays
It is possible to use individual overlays per button. The given image will be displayed with same size as the hitbox in the input descriptor.
overlay0_desc0_overlay = button.png
#### Let buttons light up when they are pressed
When using individial overlays per button it will make sense to have buttons light up when they are pressed. To do this, the alpha value will be modulated.
#### Let buttons have bigger hitbox when they are pressed
TODO:
### Triggering multiple buttons with one desc ### Triggering multiple buttons with one desc
It's possible to trigger multiple buttons (e.g. diagonals) with one overlay desc. It's possible to trigger multiple buttons (e.g. diagonals) with one overlay desc.