307 lines
11 KiB
Markdown
307 lines
11 KiB
Markdown
# 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:
|
||
```nsis
|
||
!addplugindir "path\to\plugins\x86-unicode"
|
||
```
|
||
|
||
## Building from Source
|
||
|
||
### Prerequisites
|
||
- Visual Studio 2022 or later with C++ build tools
|
||
- Python 3.x
|
||
|
||
### Build Steps
|
||
```bash
|
||
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.
|
||
|
||
```nsis
|
||
; 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
|
||
|
||
```nsis
|
||
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
|
||
```nsis
|
||
; 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
|
||
```nsis
|
||
; 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
|
||
```nsis
|
||
; 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
|
||
```nsis
|
||
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
|