---
tags: Eevee/Viewport module, Image Engine, Developer documentation
---
# Image Engine

## Glossary

Image
: Pixels...

Image Tile
: An image can be created from multiple tiles. Each tile can have its own resolution. Tiles are ordered in a grid

Image Engine
: Software component to draw images as a 2D area in an editor.

Pixel
: What is a pixel

Texel
: What is a texel

## Problem statement

What is the reason why this component exists. Which problems does it solve.
* Node editor, image editor, UV editor and movie clip editor have the requirement to draw an image on screen.
* Images have different charistics.
* Images can have multiple image tiles.
* Tiles are organized in a grid, where each cell in the grid has the same width and height in UV space.
* Tiles can have gabs between each other
* Resolution of the image could be larger than it could fit in on a GPU.
* Images can be byte or float based.
* Images can have 1, 3 or 4 channels.
* Images can have multiple views (Left, right eye)
* Images can have multiple layers (Combined, Normal, ...)
* Color management
* Alpha association

## Solution

How are the issues in the problem statement beeing solved.

### Design principles

* Upload pixels to the GPU that are visible, or around the visible area for fast panning.
* When zoomed out a lot pixels between two visible pixels might not be visible.
* When zoomed in a lot pixels further away from the visible area are not needed.
*

## Image Engine

### Class model

package blender::draw::image_engine {
    class PartialImageUpdater {
        +user: PartialUpdateUser
        --
        +ensure_image(image: Image)
    }
    
    class BatchUpdater {
        +format: GPUVertFormat
        +pos_id: int
        +uv_id: int
        --
        init_batch()
        update_batch()
        discard_batch()
    }
    note left:Updates the GPU batch to draw\na tile of the screen. (batch is stored n TextureInfo)
    
    class TextureInfo {
        +needs_full_update: bool
        +clipping_bounds: rctf
        +clipping_uv_bounds: rctf
        +batch: GPUBatch
        +texture: GPUTexture
        +last_viewport_size: float2
        --
        offset(): int2
        calc_region_bounds_from_uv_bounds(uv_to_region: float4x4)
    }
    
    class AbstractSpaceAccessor {
        +get_image(): Image
        +get_image_user(): ImageUser
        +acquire_image_buffer()
        +release_buffer()
        +get_shader_parameters()
        +use_tile_drawing()
        +init_ss_to_texture_matrix()
    }
}

#### Draw engine

The image engine is implemented as a draw engine.

@startuml
package blender::draw::image_engine {
    class ImageEngine {
        -draw_ctx: DRWContextState
        --
        begin_sync()
        image_sync()
        draw_viewport()
        draw_finish()
    }
    
    abstract class AbstractSpaceAccessor
    abstract class AbstractDrawingMode
    
    ImageEngine *- AbstractSpaceAccessor: -space
    ImageEngine *-- AbstractDrawingMode: -drawing_mode
}
@enduml

Both the space accessor and the drawing mode can be plugged into the image engine. The space accessor communicates with the editor. With the drawing mode a different way to draw the image on the screen can be used.

#### Space Accessors

The image engine is used to draw different type of editors. The communication between the editor and image engine are done via a space accessor.

Via the accessor image engine can ask for the image to display, the image user and how and where on the screen the image should be drawn.

To extend image engine for another editor a sub-class has to be created.

@startuml
package blender::draw::image_engine {
    abstract class AbstractSpaceAccessor {
        {abstract}+get_image(): Image
        {abstract}+get_image_user(): ImageUser
        {abstract}+acquire_image_buffer(): ImBuf
        {abstract}+release_buffer()
        {abstract}+get_shader_parameters(): ShaderParameters
        {abstract}+use_tile_drawing(): bool
        {abstract}+init_ss_to_texture_matrix()
    }
    
    class SpaceNodeAccessor {
        
    }
    
    class SpaceImageAccessor {
        
    }
    
    AbstractSpaceAccessor <|--SpaceImageAccessor
    AbstractSpaceAccessor <|--SpaceNodeAccessor
    
    class ShadingParameters {
        +shuffle: float4
        +far_near: float2
        +use_premul_alpha: bool
    }
    
    enum ImageDrawFlags {
        Default
        ShowAlpha
        ApplyAlpha
        Shuffling
        Depth
    }
    ShadingParameters *-- ImageDrawFlags: +flags
}
@enduml

Shading parameters contains parameters that will be used to draw the image on the screen.

- Refer to `draw/engines/image/image_space.hh`, `draw/engines/image/image_space_node.hh`, `draw/engines/image/image_space_image.hh` for the implementation.

### Drawing Modes

Image engine can have multiple drawing modes. Each drawing mode is optimized for a certain type of images. For example there could be a drawing mode that is optimized to non-tiled images upto the resolution of the area. And another for drawing higher resolution images and tiled images.

:::info
Currently a single drawing mode has been implemented that is optimized for large images.
:::

@startuml
package blender::draw::image_engine {
    abstract class AbstractDrawingMode {
        +begin_sync()
        +image_sync(image: Image, iuser: ImageUser)
        +draw_viewport()
        +draw_finish()
    }
    
    class ScreenSpaceDrawingMode
    AbstractDrawingMode <|-- ScreenSpaceDrawingMode
    
}
@enduml

### Screen space drawing mode

:::info
Explain texture streaming and the coverage of the textures with the screen.
:::

- using normalized screen coordinates to determine the uv coordinates in the corners.
- determine the uv span of the screen.
- determine the uv span of the existing textures. If the uv span is different that all textures have to be re-evaluated.
- determine which of the existing textures are not on the screen anymore based on their uv bounds. These textures can be recycled (wrap around to be placed on the screen)

## Known issues

* Pixels around the visible area aren't cached on the GPU, making panning slow.
* Resizing of areas re-allocated the GPU buffers of the viewport, clear it. which isn't fluid
* During cycles render a different approach is used, which feels more fluid, but have limitations when rendering huge textures.

## References