initial: nsSplashPNG plugin 1.0.0

2026-04-29 23:19:34 +02:00
commit db4c1b0f1e
41 changed files with 4400 additions and 0 deletions
@@ -0,0 +1,211 @@
+# nsSplashPNG - Plugin NSIS per Splash Screen PNG
+
+Plugin NSIS moderno che visualizza splash screen con supporto completo alla trasparenza alfa tramite WIC (Windows Imaging Component).
+
+## Funzionalità
+
+- **Formati Immagine Multipli**: PNG, JPEG, BMP, GIF, TIFF, ICO tramite WIC decoder
+- **Trasparenza Alfa Completa**: Supporto canale alfa per PNG/GIF tramite WIC e layered windows
+- **Velocità Fade Configurabile**: Velocità fade in/out personalizzabile (1-255 step, durata 30ms-7650ms)
+- **Esecuzione Non Bloccante**: Lo script continua dopo il fade-in mentre lo splash rimane visibile
+- **Timer Auto-Close**: Chiusura automatica configurabile dopo un numero specificato di millisecondi
+- **Click per Chiudere**: Interazione utente opzionale per chiudere lo splash
+- **No Cancel**: Impedisce all'utente di chiudere lo splash durante operazioni critiche
+- **Controllo Manuale**: Show/stop programmabile con effetti fade
+- **Supporto Multi-Monitor**: Centra lo splash sul monitor primario, corrente (mouse), per indice, o il più vicino a una coordinata
+- **Zero Warning**: Compilazione pulita con Visual Studio 2022
+
+## Installazione
+
+1. Copia `nssplashpng.dll` nella cartella dei plugin NSIS:
+   - `x86-unicode`: Per build NSIS Unicode a 32-bit
+   - `x64-unicode`: Per build NSIS Unicode a 64-bit
+   - `x86-ansi`: Per build NSIS ANSI a 32-bit
+
+2. Includi la cartella del plugin nello script:
+   ```nsis
+   !addplugindir "path\to\plugins\x86-unicode"
+   ```
+
+## Compilazione dai Sorgenti
+
+### Prerequisiti
+- Visual Studio 2022 o successivo con strumenti C++
+- Python 3.x
+
+### Passaggi
+
+```powershell
+cd nsSplashPNG
+python build_plugin.py                            # Compila tutte le architetture
+python build_plugin.py --config x86-unicode       # Solo un'architettura (x86-ansi|x86-unicode|x64-unicode|all)
+python build_plugin.py --vs-version 2026          # Versione VS specifica (2022|2026|auto)
+python build_plugin.py --clean                    # Pulizia dist/ prima della build
+python build_plugin.py --install-dir "C:\NSIS\Plugins"  # Copia in directory NSIS aggiuntiva
+python build_plugin.py --verbosity minimal        # Verbosita MSBuild (quiet|minimal|normal|detailed|diagnostic)
+```
+
+Lo script:
+- Compila per x86-unicode, x64-unicode e x86-ansi
+- Copia le DLL in `dist/{x86-unicode|amd64-unicode|x86-ansi}/`
+- Pulisce i file intermedi dalla cartella `src/Build/`
+- Supporta build parallele con ottimizzazione automatica CPU
+
+## Utilizzo
+
+### Importante: Gestione Memoria del Plugin
+
+**CRITICO**: Usare sempre il flag `/NOUNLOAD` alla prima chiamata a `show` per mantenere il plugin caricato in memoria. Senza questo, NSIS scarica il plugin dopo ogni chiamata, perdendo tutto lo stato (handle finestra, thread, ecc.), causando il fallimento di `stop`.
+
+```nsis
+; Corretto - mantiene il plugin caricato
+nssplashpng::show /NOUNLOAD 5000 /FADEIN /FADEOUT "$TEMP\splash.png"
+nssplashpng::stop /FADEOUT
+
+; Sbagliato - plugin scaricato dopo show, stop fallirà
+nssplashpng::show 5000 /FADEIN /FADEOUT "$TEMP\splash.png"
+nssplashpng::stop /FADEOUT
+```
+
+### Sintassi
+
+```nsis
+nsSplashPNG::show [/NOUNLOAD] <millisecondi> [/FADEIN [step]] [/FADEOUT [step]] [/NOCANCEL] [/MONITOR <target>] <percorso_immagine>
+nsSplashPNG::stop [/FADEOUT [step]]
+```
+
+**Nota**: Il timeout deve essere specificato subito dopo `/NOUNLOAD` (se presente), seguito da flag opzionali, con il percorso immagine come ultimo parametro.
+
+### Parametri
+
+#### Funzione show
+- `/NOUNLOAD` - **Richiesto perché stop() funzioni**: Mantiene il plugin in memoria tra le chiamate
+- `/FADEIN [step]` - Abilita effetto fade in. Step opzionale (1-255) controlla la velocità (default: 15)
+  - Step più alto = fade più veloce (255=istantaneo, 51=veloce, 15=normale, 5=lento)
+  - Formula durata: `(255 / step) × 30ms`
+- `/FADEOUT [step]` - Abilita effetto fade out alla chiusura automatica tramite timer (step opzionale)
+- `/NOCANCEL` - Disabilita click per chiudere (lo splash può essere chiuso solo programmaticamente o dal timer)
+- `/MONITOR <target>` - Seleziona il monitor su cui centrare lo splash (default: monitor primario)
+  - `PRIMARY` - Monitor primario (default)
+  - `CURRENT` o `MOUSE` - Monitor dove si trova il cursore del mouse
+  - `1`, `2`, `3`, ... - Monitor per indice 1-based (ordine di enumerazione)
+  - `POINT x y` - Monitor più vicino alle coordinate schermo fornite
+- `<millisecondi>` - Timer auto-close in millisecondi (0 = solo chiusura manuale)
+- `<percorso_immagine>` - Percorso al file immagine (PNG, JPEG, BMP, GIF, TIFF, ICO)
+
+#### Funzione stop
+- `/FADEOUT [step]` - Abilita effetto fade out alla chiusura. Step opzionale (1-255) controlla la velocità (default: 15)
+
+### Esempi
+
+#### Utilizzo Base
+```nsis
+; Mostra splash per 3 secondi (PNG con alfa) - /NOUNLOAD non necessario per solo auto-close
+nsSplashPNG::show 3000 "$EXEDIR\splash.png"
+
+; Mostra splash JPEG (opaco, senza trasparenza)
+nsSplashPNG::show 3000 "$EXEDIR\splash.jpg"
+```
+
+#### Effetti Fade
+```nsis
+; Velocità fade default (step 15, ~510ms)
+nsSplashPNG::show 3000 /FADEIN /FADEOUT "$EXEDIR\splash.png"
+
+; Fade veloce (step 51, ~150ms)
+nsSplashPNG::show 3000 /FADEIN 51 /FADEOUT 51 "$EXEDIR\splash.png"
+
+; Fade lento (step 5, ~1530ms)
+nsSplashPNG::show 5000 /FADEIN 5 /FADEOUT 5 "$EXEDIR\splash.png"
+```
+
+#### Controllo Manuale
+```nsis
+; CRITICO: Usare /NOUNLOAD quando si usa stop() per chiudere manualmente
+nsSplashPNG::show /NOUNLOAD 0 /NOCANCEL "$EXEDIR\splash.png"
+
+; ... operazioni di installazione ...
+
+; Chiudi con fade out
+nsSplashPNG::stop /FADEOUT
+```
+
+## Dettagli Tecnici
+
+### Implementazione
+- **Libreria Grafica**: WIC (Windows Imaging Component) tramite windowscodecs.lib
+- **Formato Immagine**: 32bppPBGRA (alfa pre-moltiplicato) per corretta trasparenza
+- **Tipo Finestra**: Layered window con `WS_EX_LAYERED | WS_EX_TOPMOST | WS_EX_TOOLWINDOW`
+- **Trasparenza**: `UpdateLayeredWindow` con blending alfa per pixel
+- **Rendering**: Accelerato hardware tramite `UpdateLayeredWindow` con `ULW_ALPHA`
+- **Animazione**: Timer da 30ms per fade fluido (range alfa 0-255)
+- **Threading**: Thread finestra in background per esecuzione non bloccante
+
+### Confronto con nsAdvsplash
+
+| Funzionalità | nsAdvsplash | nsSplashPNG |
+|--------------|-------------|-------------|
+| Supporto Alfa PNG | Parziale | Completo |
+| Effetti Fade | Sì | Sì |
+| Metodo Trasparenza | Color key | Alfa per pixel |
+| API Grafica | GDI | WIC |
+| Tipo Finestra | Standard | Layered |
+| Click per Chiudere | Sì | Sì |
+| Warning Compilazione | Alcuni | Nessuno |
+
+### Formati Immagine Supportati
+
+WIC rileva e decodifica automaticamente i seguenti formati:
+- **PNG** - Supporto completo trasparenza alfa
+- **JPEG/JPG** - Senza trasparenza (opaco)
+- **BMP** - Trasparenza alfa se a 32-bit, altrimenti opaco
+- **GIF** - Supporto trasparenza base
+- **TIFF** - Trasparenza alfa se supportata dalla variante
+- **ICO** - Formato icona con alfa
+- **WMP** - Windows Media Photo
+
+### Requisiti di Sistema
+- Windows Vista o successivo (per supporto layered window)
+- WIC - Windows Imaging Component (incluso da Windows Vista in poi)
+
+## Risoluzione Problemi
+
+### Immagine non visibile
+- Verificare che il percorso del file immagine sia corretto e accessibile
+- Controllare che il file sia in un formato supportato
+- Verificare che WIC possa decodificare il file immagine specifico
+
+### Nessuna trasparenza
+- Confermare che il PNG abbia canale alfa (non solo RGB)
+- Verificare di usare la DLL plugin corretta per la versione NSIS
+
+### Effetti fade non fluidi
+- Comportamento normale - il fade usa timer 30ms con incrementi alfa di 15 step
+- Durata totale fade ≈ 450-500ms
+
+## Licenza
+
+Creato per il sistema di installazione NSIS.
+
+## Crediti
+
+- NSIS Plugin API
+- WIC - Windows Imaging Component
+- Windows Layered Windows API (`UpdateLayeredWindow`)
+- Sistema di build ispirato al plugin nsProcess
+
+## Cronologia Versioni
+
+### 1.0.0 (Corrente)
+- Supporto trasparenza alfa PNG completo tramite WIC
+- Blending alfa per pixel con `UpdateLayeredWindow`
+- Effetti fade in/out (30ms, 15 step)
+- Timer auto-close con timeout configurabile
+- Click per chiudere con disabilitazione opzionale (`/NOCANCEL`)
+- Build x86-unicode, x64-unicode e x86-ansi
+- Zero warning di compilazione
+- Sistema di build ottimizzato con compilazione parallela
+
+---
+
+*See [README.md](README.md) for the English version.*