nsis-plugin-nssplashpng/docs/README.md

nsSplashPNG - PNG Splash Screen Plugin for NSIS

A modern NSIS plugin that displays splash screens with full alpha transparency support using WIC (Windows Imaging Component).

Features

• Multiple Image Formats: PNG, JPEG, BMP, GIF, TIFF, ICO via WIC decoder
• Full Alpha Transparency: Proper PNG/GIF alpha channel support via WIC and layered windows
• Configurable Fade Speed: Customizable fade in/out speed (1-255 steps, 30ms-7650ms duration)
• Non-Blocking Execution: Script continues after fade-in while splash stays visible
• Auto-Close Timer: Configurable automatic close after specified milliseconds
• Click-to-Close: Optional user interaction to close splash
• No Cancel Option: Prevent users from closing splash during critical operations
• Manual Control: Programmatic show/stop with fade effects
• Zero Warnings: Clean compilation with Visual Studio 2022

Installation

1. Copy nssplashpng.dll to your NSIS plugins directory:

   • x86-unicode: For 32-bit NSIS Unicode builds
   • x64-unicode: For 64-bit NSIS Unicode builds
   • x86-ansi: For 32-bit NSIS ANSI builds

2. Include the plugin directory in your script:

   !addplugindir "path\to\plugins\x86-unicode"
   

Building from Source

Prerequisites

• Visual Studio 2022 or later with C++ build tools
• Python 3.x

Build Steps

cd nsSplashPNG
python build_plugin.py  # Builds all configurations
python build_plugin.py --configs x86-unicode  # Build specific config

The script will:

• Build for x86-unicode, x64-unicode, and x86-ansi configurations
• Copy DLLs to ../plugins/{x86-unicode|amd64-unicode|x86-ansi}/ directories
• Clean up intermediate build artifacts from src/Build/
• Supports parallel builds with automatic CPU optimization

Usage

Important: Plugin Memory Management

CRITICAL: Always use /NOUNLOAD flag on the first show call to keep the plugin loaded in memory. Without this, NSIS unloads the plugin after each call, losing all state (window handles, threads, etc.), causing stop to fail.

; Correct - keeps plugin loaded
nssplashpng::show /NOUNLOAD 5000 /FADEIN /FADEOUT "$TEMP\splash.png"
nssplashpng::stop /FADEOUT

; Wrong - plugin unloaded after show, stop will fail
nssplashpng::show 5000 /FADEIN /FADEOUT "$TEMP\splash.png"
nssplashpng::stop /FADEOUT

Syntax

nsSplashPNG::show [/NOUNLOAD] <milliseconds> [/FADEIN [step]] [/FADEOUT [step]] [/NOCANCEL] <image_path>
nsSplashPNG::stop [/FADEOUT [step]]

Note: The timeout must be specified immediately after /NOUNLOAD (if present), followed by optional flags, with the image path as the last parameter.

Parameters

show function

• /NOUNLOAD - Required for stop() to work: Keeps plugin in memory between calls
• /FADEIN [step] - Enable fade in effect. Optional step (1-255) controls speed (default: 15)
  • Higher step = faster fade (255=instant, 51=fast, 15=normal, 5=slow)
  • Duration formula: (255 / step) × 30ms
• /FADEOUT [step] - Enable fade out effect when auto-closing via timer (optional step)
• /NOCANCEL - Disable click-to-close (splash can only be closed programmatically or by timer)
• <milliseconds> - Auto-close timer in milliseconds (0 = manual close only)
• <image_path> - Path to image file (PNG, JPEG, BMP, GIF, TIFF, ICO)

stop function

• /FADEOUT [step] - Enable fade out effect when closing. Optional step (1-255) controls speed (default: 15)

Examples

Basic Usage

; Show splash for 3 seconds (PNG with alpha) - no /NOUNLOAD needed for auto-close only
nsSplashPNG::show 3000 "$EXEDIR\splash.png"

; Show JPEG splash (opaque, no transparency)
nsSplashPNG::show 3000 "$EXEDIR\splash.jpg"

Fade Effects

; Default fade speed (step 15, ~510ms)
nsSplashPNG::show 3000 /FADEIN /FADEOUT "$EXEDIR\splash.png"

; Fast fade (step 51, ~150ms)
nsSplashPNG::show 3000 /FADEIN 51 /FADEOUT 51 "$EXEDIR\splash.png"

; Slow fade (step 5, ~1530ms)
nsSplashPNG::show 5000 /FADEIN 5 /FADEOUT 5 "$EXEDIR\splash.png"

; Instant (step 255, ~30ms)
nsSplashPNG::show 3000 /FADEIN 255 /FADEOUT 255 "$EXEDIR\splash.png"

; Different speeds for fade-in and fade-out
nsSplashPNG::show 3000 /FADEIN 51 /FADEOUT 5 "$EXEDIR\splash.png"

Manual Control

; CRITICAL: Use /NOUNLOAD when using stop() to close manually
nsSplashPNG::show /NOUNLOAD 0 /NOCANCEL "$EXEDIR\splash.png"

; ... do installation work ...

; Close with fade out
nsSplashPNG::stop /FADEOUT

; Or close with custom fade speed
nsSplashPNG::stop /FADEOUT 51

Real Installer Example

Name "My Application"
OutFile "setup.exe"
InstallDir "$PROGRAMFILES\MyApp"

!addplugindir "plugins\x86-unicode"

Page instfiles

Section "Main Installation"
    ; Show splash with fade in, prevent user closing, no auto-close
    ; CRITICAL: /NOUNLOAD required for stop() to work
    nsSplashPNG::show /NOUNLOAD 0 /NOCANCEL /FADEIN "$EXEDIR\splash.png"
    
    ; Install files
    SetOutPath "$INSTDIR"
    File /r "app\*.*"
    
    ; Create shortcuts
    CreateDirectory "$SMPROGRAMS\MyApp"
    CreateShortcut "$SMPROGRAMS\MyApp\MyApp.lnk" "$INSTDIR\myapp.exe"
    
    ; Close splash with fade out
    nsSplashPNG::stop /FADEOUT
SectionEnd

Additional Examples

See the examples/ folder for more usage demonstrations:

• example_basic.nsi - Simple splash with auto-close timer
• example_advanced.nsi - Manual control with fade effects
• example_formats.nsi - Multi-format support (PNG, JPEG, BMP, GIF)
• example_fade_speed.nsi - Customizable fade speed demonstrations
• example_nonblocking.nsi - Non-blocking behavior with background processing

Technical Details

Implementation

• Graphics Library: WIC (Windows Imaging Component) via windowscodecs.lib
• Image Format: 32bppPBGRA (pre-multiplied alpha) for proper transparency
• Window Type: Layered windows with WS_EX_LAYERED | WS_EX_TOPMOST | WS_EX_TOOLWINDOW
• Transparency: UpdateLayeredWindow with per-pixel alpha blending
• Rendering: Hardware-accelerated via UpdateLayeredWindow with ULW_ALPHA
• Animation: 30ms timer intervals for smooth fade (0-255 alpha range)
  • Configurable step size (default: 15 steps = ~510ms duration)
  • Duration formula: (255 / step) × 30ms
• Threading: Background window thread for non-blocking execution
  • show() returns after fade-in completes
  • Window stays open in background
  • stop() waits for fade-out to complete before returning
• Plugin State: Requires /NOUNLOAD to maintain global variables (window handles, threads) between calls

Comparison with nsAdvsplash

Feature	nsAdvsplash	nsSplashPNG
PNG Alpha Support	Partial	Full
Fade Effects	Yes	Yes
Transparency Method	Color key	Per-pixel alpha
Graphics API	GDI	WIC
Window Type	Standard	Layered
Click-to-Close	Yes	Yes
Compilation Warnings	Some	None

Supported Image Formats

WIC automatically detects and decodes the following formats:

• PNG - Full alpha transparency support
• JPEG/JPG - No transparency (opaque)
• BMP - Alpha transparency if 32-bit, otherwise opaque
• GIF - Basic transparency support
• TIFF - Alpha transparency if supported by variant
• ICO - Icon format with alpha
• WMP - Windows Media Photo

Note: Formats without alpha channels (JPEG, 24-bit BMP) will display as opaque images.

System Requirements

• Windows Vista or later (for layered window support)
• WIC - Windows Imaging Component (included with Windows Vista+)

API Reference

Exported Functions

show()

Creates and displays a splash screen window in a background thread.

Parameters (parsed from NSIS stack in reverse order):

1. Timeout in milliseconds (integer, 0 = manual close only)
2. /FADEIN [step] - Optional fade in with configurable step (1-255, default: 15)
3. /FADEOUT [step] - Optional auto fade out with configurable step (1-255, default: 15)
4. /NOCANCEL - Disable click-to-close
5. /NOUNLOAD - Required for stop() to work: Keeps plugin in memory
6. Image path (string) - last parameter

Behavior:

• Cleans up any previous window/thread
• Loads image with WIC (IWICImagingFactory, IWICBitmapDecoder)
• Supports PNG, JPEG, BMP, GIF, TIFF, ICO, WMP formats
• Converts to 32bppPBGRA format for proper alpha handling
• Creates centered topmost layered window
• Uses UpdateLayeredWindow for per-pixel alpha transparency
• Starts background thread with window message loop
• Applies fade in effect if /FADEIN specified (30ms timer with configurable steps)
• Sets auto-close timer if timeout > 0
• Enables click-to-close unless /NOCANCEL specified
• Returns control after fade-in completes (non-blocking)
• Without /NOUNLOAD, plugin unloads and loses all state

Return value: Pushes "success" to NSIS stack

stop()

Closes the splash screen window with optional fade-out.

Parameters (parsed from NSIS stack):

1. /FADEOUT [step] - Optional fade out with configurable step (1-255, default: 15)

Behavior:

• If /FADEOUT specified:
  • Starts fade-out timer (30ms intervals)
  • Waits for fade to complete: (255 / step) × 30ms
  • Destroys window after fade completes
• Otherwise:
  • Immediately destroys window
• Requires show() to have used /NOUNLOAD or window handle will be NULL

Return value: Pushes "success" to NSIS stack

Behavior:

• Applies fade out effect if /FADEOUT specified (30ms timer, 15 steps)
• Destroys window and releases WIC resources
• Terminates splash thread and cleans up handles

Troubleshooting

Image not showing

• Verify image file path is correct and accessible
• Check that image file is in a supported format (PNG, JPEG, BMP, GIF, TIFF, ICO)
• Ensure NSIS can read the file at install time
• Verify WIC can decode the specific image file variant

No transparency

• Confirm PNG has alpha channel (not just RGB)
• Verify you're using the correct plugin DLL for your NSIS version
• Check Windows version supports layered windows (Vista+)

Fade effects not smooth

• Normal behavior - fade uses 30ms timer with 15-step alpha increments
• Total fade duration ≈ 450-500ms

License

Created for NSIS installer system.

Credits

• NSIS Plugin API
• WIC - Windows Imaging Component
• Windows Layered Windows API (UpdateLayeredWindow)
• Build system inspired by nsProcess plugin

Version History

1.0.0 (Current)

• Full PNG alpha transparency support via WIC
• Per-pixel alpha blending with UpdateLayeredWindow
• Fade in/out effects (30ms, 15 steps)
• Auto-close timer with configurable timeout
• Click-to-close with optional disable (/NOCANCEL)
• Blocks installer until splash closes
• x86-unicode, x64-unicode, and x86-ansi builds
• Zero compilation warnings with guarded macro definitions
• Optimized build system with parallel compilation support