Simone/nsis-plugin-nssplashpng
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

initial: nsSplashPNG plugin 1.0.0

Browse Source
This commit is contained in:
Simone
2026-04-29 23:19:34 +02:00
commit db4c1b0f1e
41 changed files with 4400 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+306
View File
@@ -0,0 +1,306 @@
# 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