Simone/nsis-plugin-nssplashpng
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
Files
27a2c60d1965c7a6fc4d1e3ad8bfcd839424dcfa
nsis-plugin-nssplashpng/README.md
T

13 KiB
Raw Blame History

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
  • Multi-Monitor Support: Center splash on primary, current (mouse), specific index, or nearest to a screen coordinate
  • 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                            # Build all architectures
python build_plugin.py --config x86-unicode       # Single architecture (x86-ansi|x86-unicode|x64-unicode|all)
python build_plugin.py --vs-version 2026          # Specific VS version (2022|2026|auto)
python build_plugin.py --clean                    # Clean dist/ before build
python build_plugin.py --install-dir "C:\NSIS\Plugins"  # Copy to additional NSIS directory
python build_plugin.py --verbosity minimal        # MSBuild verbosity (quiet|minimal|normal|detailed|diagnostic)

The script will:

  • Build for x86-unicode, x64-unicode, and x86-ansi configurations
  • Copy DLLs to dist/{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] [/MONITOR <target>] <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)
  • /MONITOR <target> - Select the monitor on which to center the splash (default: primary monitor)
    • PRIMARY - Primary monitor (default)
    • CURRENT or MOUSE - Monitor where the mouse cursor is
    • 1, 2, 3, ... - Monitor by 1-based index (enumeration order)
    • POINT x y - Monitor nearest to the given screen coordinates (uses MONITOR_DEFAULTTONEAREST); useful to target the monitor where an application window was last open
  • <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

Monitor Selection

; Show on primary monitor (default)
nsSplashPNG::show /NOUNLOAD 0 /NOCANCEL "$EXEDIR\splash.png"

; Show on the monitor where the mouse cursor is
nsSplashPNG::show /NOUNLOAD 0 /NOCANCEL /MONITOR CURRENT "$EXEDIR\splash.png"

; Show on the second monitor (by 1-based index)
nsSplashPNG::show /NOUNLOAD 0 /NOCANCEL /MONITOR 2 "$EXEDIR\splash.png"

; Show on the monitor nearest to a known screen coordinate
; (e.g. where an application window was previously displayed)
nsSplashPNG::show /NOUNLOAD 0 /MONITOR POINT -1906 200 /FADEIN "$EXEDIR\splash.png"

nsSplashPNG::stop /FADEOUT

Note on parameter order: /MONITOR POINT x y must be placed before /FADEIN//FADEOUT. The /FADEIN parser reads ahead one token to check for a custom step; if that token starts with /, it is requeued — but a subsequent popstring() in the loop will overwrite it before /MONITOR can be processed.

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. /MONITOR <target> - Monitor selection (see parameter docs); must appear before /FADEIN
  6. /NOUNLOAD - Required for stop() to work: Keeps plugin in memory
  7. 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 on the selected monitor:
    • MONITOR_MODE_PRIMARY (default) — GetSystemMetrics(SM_CX/CYSCREEN)
    • MONITOR_MODE_MOUSE — GetCursorPos + MonitorFromPoint
    • MONITOR_MODE_INDEX — EnumDisplayMonitors by 0-based index
    • MONITOR_MODE_POINT — MonitorFromPoint(x, y, MONITOR_DEFAULTTONEAREST)
  • 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

See README_IT.md for the Italian version.

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
Reference in New Issue View Git Blame Copy Permalink