HPL2/Tutorials/ShowScreenImage()

Introduction

ATDD version 1.5 added the ShowScreenImage() function, which was previously available in AAMFP. Some of the workings of this function are a little counter-intuitive, so the purpose of this page is to explain it a little. This is based off of the author's experiments in ATDD 1.5, so it's not definitive! It's also assumed that these notes apply to AAMFP in the same way, but that has not been tested.

Function

void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);

Displays an image file directly onto the screen.

1. asImageName - The image file to render (.jpg, .png, .tga, .dds) (see Size)
2. afX - The X position of the image (see Placement)
3. afY - The Y position of the image (see Placement)
4. afScale - The size of the image in pixels (see Size)
5. abUseRelativeCoordinates - If true, X and Y represent a fraction of the entire screen resoltion, otherwise they are pixel co-ordinates (see Placement)
6. afDuration - The duration, in seconds, that the image is displayed for (see Timing)
7. afFadeIn - The time, in seconds, to fade in the image (see Timing)
8. afFadeOut - The time, in seconds, to fade out the image (see Timing)

Size

Note that the afScale argument is not actually the scale of the image: it is the size in pixels. This is not relative and does not take the screen resolution into account, so an image will appear bigger or smaller at lower or higher resolutions respectively. The image will be rendered onscreen as a square quad, even if the image file is non square. So if the desired effect is to display a non-square image, it will need to be padded out with transparent pixels in order to make it render without distortion.

Placement

The origin of the screen-space is the centre. This means that [0,0] is the centre of the screen regardless of screen resolution, and regardless of abUseRelativeCoordinates. The origin of the image-space is the top-left. This means that the co-ordinates define where the top-left corner of the image will go. If abUseRelativeCoordinates is false, then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, expressed as actual pixels. If abUseRelativeCoordinates is true, then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, expressed as a fraction of the screen resolution width or height.

Timing

The total time that the image will be displayed is afFadeIn + afDuration + afFadeOut. afDuration counts from when the fade in is finished. afFadeOut counts from when afDuration is finished.

Uses

WIP - examples to follow