HPL2/Tutorials/ShowScreenImage() - Revision history

Mrbehemo at 17:27, 4 January 2024

2024-01-04T17:27:42Z

Mrbehemo at 17:26, 4 January 2024

2024-01-04T17:26:53Z

Mrbehemo at 17:11, 4 January 2024

2024-01-04T17:11:23Z

Mrbehemo: Added -1 size option.

2024-01-04T17:10:09Z

Added -1 size option.

Mrbehemo: Added examples and conclusion.

2024-01-04T16:54:32Z

Added examples and conclusion.

Mrbehemo: Mrbehemo moved page ShowScreenImage() to HPL2/Tutorials/ShowScreenImage()

2024-01-04T15:05:26Z

Mrbehemo moved page ShowScreenImage() to HPL2/Tutorials/ShowScreenImage()

Mrbehemo: Notes about using the ShowScreenImage() function in ATTD 1.5 and AAMFP.

2024-01-04T15:04:41Z

Notes about using the ShowScreenImage() function in ATTD 1.5 and AAMFP.

New page

=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=
<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

Displays an image file directly onto the screen.

# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds) (see Size)
# ''afX'' - The X position of the image (see Placement)
# ''afY'' - The Y position of the image (see Placement)
# ''afScale'' - The size of the image in pixels (see Size)
# ''abUseRelativeCoordinates'' - If true, X and Y represent a fraction of the entire screen resoltion, otherwise they are pixel co-ordinates (see Placement)
# ''afDuration'' - The duration, in seconds, that the image is displayed for (see Timing)
# ''afFadeIn'' - The time, in seconds, to fade in the image (see Timing)
# ''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

@@ Line 68: / Line 68: @@
 ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
 // With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
-// The centre of the image would be at the centre of the screen at 4k, but would move towards the bottom left with lower resolutions.
+// The centre of the image would be at the centre of the screen at 4k, but would move towards the bottom-right with lower resolutions.
 // At lower resolutions the right and bottom of the image would be cropped. At higher resolutions it would not fill the screen.

@@ Line 10: / Line 10: @@
 Displays an image file directly onto the screen.
-# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds) (see Size)
+# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds) (see [[HPL2/Tutorials/ShowScreenImage()#Size|Size]])
-# ''afX'' - The X position of the image (see Placement)
+# ''afX'' - The X position of the image, relative to the centre of the screen (see [[HPL2/Tutorials/ShowScreenImage()#Placement|Placement]])
-# ''afY'' - The Y position of the image (see Placement)
+# ''afY'' - The Y position of the image, relative to the centre of the screen (see [[HPL2/Tutorials/ShowScreenImage()#Placement|Placement]])
-# ''afScale'' - The size of the image in pixels, or original image size if negative (see Size)
+# ''afScale'' - The size of the image in pixels, or original image size if negative (see [[HPL2/Tutorials/ShowScreenImage()#Size|Size]])
-# ''abUseRelativeCoordinates'' - If true, X and Y represent a fraction of the entire screen resoltion, otherwise they are pixel co-ordinates (see Placement)
+# ''abUseRelativeCoordinates'' - If true, X and Y represent a fraction of the entire screen resoltion, otherwise they are pixel co-ordinates (see [[HPL2/Tutorials/ShowScreenImage()#Placement|Placement]])
-# ''afDuration'' - The duration, in seconds, that the image is displayed for (see Timing)
+# ''afDuration'' - The duration, in seconds, that the image is displayed for (see [[HPL2/Tutorials/ShowScreenImage()#Timing|Timing]])
-# ''afFadeIn'' - The time, in seconds, to fade in the image (see Timing)
+# ''afFadeIn'' - The time, in seconds, to fade in the image (see [[HPL2/Tutorials/ShowScreenImage()#Timing|Timing]])
-# ''afFadeOut'' - The time, in seconds, to fade out the image (see Timing)
+# ''afFadeOut'' - The time, in seconds, to fade out the image (see [[HPL2/Tutorials/ShowScreenImage()#Timing|Timing]])

@@ Line 22: / Line 22: @@
 =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.
+* If the size is specified, 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.
@@ Line 48: / Line 49: @@
 // From top-left:
-ShowScreenImage("image.dds", -0.45f, -0.45f, 100.0f, true, 2.0f, 1.0f, 2.0f);
+ShowScreenImage("image.dds", -0.45f, -0.45f, -1.0f, true, 2.0f, 1.0f, 2.0f);
-// Size: 100 x 100 pixels
+// Size: original pixel size and shape of the image file
 // Placement: near the top-left corner, with a 5% margin relative to the screen size
 // Timing: 5 seconds, including fading
@@ Line 79: / Line 80: @@
 =Conclusion=
-There are lots of things you can do with ShowScreenImage() if you use it creatively...
+There are lots of things you can do with ShowScreenImage() if you use it creatively!
-If you need to place an image relative the the right-hand edge or bottom of the screen, or relative to the screen resolution, it might be tricky, and might not be future-proof.
+...But if you need to place an image relative the the right-hand edge or bottom of the screen, or relative to the screen resolution, it might be tricky, and might not be future-proof.

@@ Line 21: / Line 21: @@
 =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.
+* 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.
+* 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 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.
+* 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 ''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''.
+* 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''.
+* 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.
+* ''afDuration'' counts from when the fade in is finished. ''afFadeOut'' counts from when ''afDuration'' is finished.
-=Uses=
+=Examples=
-WIP - examples to follow
+<syntaxhighlight lang="c++">

← Older revision	Revision as of 15:05, 4 January 2024
(No difference)