https://github.com/thiojoe/win-svg-thumbs-rust

A native Windows SVG thumbnail handler for File Explorer written in Rust, using only Microsoft's official Windows API bindings
https://github.com/thiojoe/win-svg-thumbs-rust

shell-extension svg thumbnails windows

Last synced: 12 months ago
JSON representation

A native Windows SVG thumbnail handler for File Explorer written in Rust, using only Microsoft's official Windows API bindings

• Host: GitHub
• URL: https://github.com/thiojoe/win-svg-thumbs-rust
• Owner: ThioJoe
• License: mit
• Created: 2025-06-27T04:09:46.000Z (about 1 year ago)
• Default Branch: master
• Last Pushed: 2025-06-27T17:42:37.000Z (about 1 year ago)
• Last Synced: 2025-06-27T17:46:09.439Z (about 1 year ago)
• Topics: shell-extension, svg, thumbnails, windows
• Language: Rust
• Homepage:
• Size: 26.4 KB
• Stars: 13
• Watchers: 0
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Thio's SVG Thumbnail Extension for Windows Explorer

A high-performance thumbnail provider for Windows that generates explorer thumbnails for `.svg` and `.svgz` files, written in Rust, with no third party dependencies.

## Why Use This One?

  

    

      No Third-Party Dependencies

      Built using only official Microsoft-published Rust crates (found in the windows‑rs repo).

    

    

      Works Purely Through Windows API

      

        Operates purely through the built-in Windows API for rendering and COM integration. Just a single native DLL.

        


          ↳ No third party libraries that may go out of date or add overhead

        

      

    

    

      Trusted Certificate Signed

      

        Signed via Azure Trusted Signing, which requires rigorous verification of real-world identity.

        


          ↳ Proves it's not made by an unaccountable/unknown developer

        

      

    

  


## Screenshot







## How to Install

1.  Go to the [Releases](https://github.com/ThioJoe/win-svg-thumbs-rust/releases) page.

2.  Download the latest `win_svg_thumbs.dll` file. Put it somewhere it can remain.

3.  Open a Command Prompt with **administrator privileges**.

     - (Administrator is required or you will get error `0x80004005` for lack of permission)

5.  Navigate to the directory where you saved the `.dll` file.

6.  Run the following command to register the DLL:

    ```

    regsvr32 win_svg_thumbs.dll

    ```

## Usage

Once the DLL is registered, Windows Explorer will automatically use this provider to display thumbnails for `.svg` and `.svgz` files.

To uninstall, run the following command in an administrator Command Prompt:

  ```

  regsvr32 /u win_svg_thumbs.dll

  ```

## How it works (Technical Details)

When Windows Explorer needs a thumbnail for a `.svg` file, it interacts with this DLL through a series of steps:

1.  **Initialization**: Explorer provides the `.svg` file's data as a stream to the DLL. The provider reads this entire stream into memory.

2.  **Direct2D Rendering**:

    * The provider uses the **Direct2D** graphics API for high-performance, hardware-accelerated rendering.

    * It creates a GPU-based bitmap to serve as a render target.

    * The Direct2D API turns the SVG data into a `SvgDocument` object. The `viewport` attribute is set to the thumbnail size requested by Explorer.

    * The `width` and `height` attributes are removed from the root `` element before drawing, which I discovered causes the `DrawSvgDocument` method to autoscale the image to the viewport, avoiding the need to do any manual scaling to fill the thumbnail.

    * The `SvgDocument` is then drawn onto the render target bitmap.

    * The `unpremultiply` effect is then applied to the bitmap, because the standard Windows GDI requires straight alpha.

      * The un-premultiplication step is necessary for displaying transparency correctly and prevents dark edges from appearing on the final thumbnail.

3.  **Pixel Data Transfer**:

    * The rendered image is copied from the GPU render target to a "staging" bitmap on the CPU, which allows the program to access the raw pixel data.

    * This data is in a 32-bit BGRA format with **straight alpha** (after the unpremultiply effect).

    * Note: Although the staging bitmap is declared to Direct2D as having premultiplied alpha format (required for proper bitmap operations), the actual pixel values contain straight alpha data due to the unpremultiply effect. Direct2D normally only works with premultiplied alpha, but this doesn't matter at this point since we're just copying the data out to GDI.

4.  **Creating the Final Thumbnail**:

    * A standard Windows GDI `HBITMAP` is created, which is the final format Explorer needs for the thumbnail.

    * The pixel data is copied from the staging bitmap to the final `HBITMAP`.

5.  **Safety**: The entire thumbnail generation process is wrapped in a panic handler (`catch_unwind`). This ensures that if any unexpected error occurs during rendering, it will not crash the host application (e.g., `explorer.exe`).

## How to Compile it Yourself

### Prerequisites

* Setup Rust on Windows: [See these instructions](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup)

### Instructions

1.  Clone the repository:

    ```

    git clone https://github.com/ThioJoe/win-svg-thumbs-rust

    ```

2.  Navigate to the project directory:

    ```

    cd win-svg-thumbs-rust

    ```

3.  Build the project in release mode:

    ```

    cargo build --release

    ```

4.  The compiled DLL will be located in the `target/release` directory.