BioGTK.SlideRenderer Class Reference

Public Member Functions
	SlideRenderer (SlideGLArea glArea)
void	SetSource (OpenSlideBase source)
void	SetSource (SlideBase source)
async Task< bool >	PopulateZarrStatisticsAsync (BioImage image, ZCT coordinate, CancellationToken ct=default)
async Task< double?>	SampleZarrPixelAsync (BioImage image, ZCT coordinate, int pixelX, int pixelY, CancellationToken ct=default)
void	ClearCache (bool resetLevel=true, bool cancelActiveFetches=true)
void	InvalidateRenderState (bool cancelActiveFetches=true)
	Marks all in-flight tile work as stale. Call this before changing threshold/range state so old tiles cannot overwrite the current view.
void	InvalidateViewport ()
	Marks screen-space layout work as stale without cancelling tile I/O. Tile pixels are independent of the current pan/zoom and remain useful cache entries for the next viewport render.
async Task	UpdateViewAsync (PointD pyramidalOrigin, int viewportWidth, int viewportHeight, double resolution, ZCT coordinate)

Properties
bool	LastRenderSkipped [get]
int	CurrentLevel [get]
int	CachedTextureCount [get]

Detailed Description

Definition at line 15 of file SlideRenderer.cs.

Constructor & Destructor Documentation

SlideRenderer()

BioGTK.SlideRenderer.SlideRenderer

(

SlideGLArea

glArea

)

Definition at line 61 of file SlideRenderer.cs.

        {
            _glArea = glArea;
        }

Member Function Documentation

ClearCache()

void BioGTK.SlideRenderer.ClearCache	(	bool	resetLevel = true,
		bool	cancelActiveFetches = true )

Definition at line 304 of file SlideRenderer.cs.

        {
            // Clearing the visible tile cache must also invalidate any in-flight
            // fetches. Otherwise an old Z/C/T request can finish after the
            // coordinate changes and repopulate the GPU cache with stale tiles.
            Interlocked.Increment(ref _renderStateVersion);
            if (cancelActiveFetches)
                CancelActiveTileFetches();
 
            _glArea.ClearTextureCache();
            lock (_uploadedTileLock)
            {
                _uploadedTiles.Clear();
                _uploadedTileInfos.Clear();
            }
            if (resetLevel)
                _currentLevel = -1;
            _tileCache?.Clear();
            _openTileCache?.cache.cacheMap.Clear();
 
            _slideBase?.cache?.Clear();
            _openSlideBase?.cache?.cache.cacheMap.Clear();
            _displayRangeSeedLevel = -1;
 
            lock (_pendingLevelSwitchLock)
            {
                _pendingLevelRenderInfos = null;
                _pendingLevel = -1;
                _pendingPreviousLevel = -1;
            }
 
            lock (_pendingTileFetchLock)
            {
                _pendingTileFetches.Clear();
                _tileRetryCounts.Clear();
            }
        }

InvalidateRenderState()

void BioGTK.SlideRenderer.InvalidateRenderState

(

bool

cancelActiveFetches = true

)

Marks all in-flight tile work as stale. Call this before changing threshold/range state so old tiles cannot overwrite the current view.

Definition at line 346 of file SlideRenderer.cs.

        {
            Interlocked.Increment(ref _renderStateVersion);
            if (cancelActiveFetches)
                CancelActiveTileFetches();
            lock (_pendingTileFetchLock)
            {
                _pendingTileFetches.Clear();
                _tileRetryCounts.Clear();
            }
        }

InvalidateViewport()

void BioGTK.SlideRenderer.InvalidateViewport

(

)

Marks screen-space layout work as stale without cancelling tile I/O. Tile pixels are independent of the current pan/zoom and remain useful cache entries for the next viewport render.

Definition at line 363 of file SlideRenderer.cs.

        {
            Interlocked.Increment(ref _viewportVersion);
            lock (_pendingLevelSwitchLock)
            {
                _pendingLevelRenderInfos = null;
                _pendingLevel = -1;
                _pendingPreviousLevel = -1;
            }
        }

PopulateZarrStatisticsAsync()

async Task< bool > BioGTK.SlideRenderer.PopulateZarrStatisticsAsync	(	BioImage	image,
		ZCT	coordinate,
		CancellationToken	ct = default )

Definition at line 173 of file SlideRenderer.cs.

        {
            if (image?.IsZarrSource != true || image.Channels == null || image.Channels.Count == 0)
                return false;
 
            List<ResolutionLevelNode> levels = await GetDirectZarrLevelsAsync(image, ct).ConfigureAwait(false);
            if (levels == null || levels.Count == 0 || image.Resolutions == null || image.Resolutions.Count == 0)
                return false;
 
            // Use a compact but representative pyramid level. This avoids reading
            // the full-resolution plane merely to draw a small histogram.
            int usableLevels = Math.Min(levels.Count, image.Resolutions.Count);
            int sampleLevel = 0;
            long bestDistance = long.MaxValue;
            const int targetDimension = 1024;
            for (int level = 0; level < usableLevels; level++)
            {
                int maxDimension = Math.Max(image.Resolutions[level].SizeX, image.Resolutions[level].SizeY);
                long distance = Math.Abs((long)maxDimension - targetDimension);
                if (maxDimension > 0 && distance < bestDistance)
                {
                    bestDistance = distance;
                    sampleLevel = level;
                }
            }
 
            int width = image.Resolutions[sampleLevel].SizeX;
            int height = image.Resolutions[sampleLevel].SizeY;
            if (width <= 0 || height <= 0)
                return false;
 
            ResolutionLevelNode levelNode = levels[sampleLevel];
            bool packedPlanarRgb = image.Resolutions[0].PixelFormat == PixelFormat.Format48bppRgb &&
                                   image.Channels.Count == 1;
            int sourceChannelCount = packedPlanarRgb
                ? Math.Max(3, image.RGBChannelCount)
                : image.Channels.Count;
            var imageStatistics = new Statistics(image.bitsPerPixel > 8);
            bool gotAnyStatistics = false;
 
            for (int channelIndex = 0; channelIndex < image.Channels.Count; channelIndex++)
            {
                int samplesForChannel = packedPlanarRgb ? sourceChannelCount : 1;
                var channelStatistics = new Statistics[samplesForChannel];
                for (int sample = 0; sample < samplesForChannel; sample++)
                {
                    ct.ThrowIfCancellationRequested();
                    int sourceChannel = packedPlanarRgb ? sample : channelIndex;
                    var plane = await levelNode.ReadTileAsync(
                        0, 0, width, height,
                        z: coordinate.Z,
                        c: sourceChannel,
                        t: coordinate.T,
                        ct: ct).ConfigureAwait(false);
                    byte[] data = plane?.Data;
                    if (data == null || data.Length == 0)
                        continue;
 
                    int bytesPerSample = Math.Max(1, data.Length / Math.Max(1, width * height));
                    int bitsPerSample = bytesPerSample >= 2 ? 16 : 8;
                    PixelFormat statisticsFormat = bitsPerSample > 8
                        ? PixelFormat.Format16bppGrayScale
                        : PixelFormat.Format8bppIndexed;
                    int stride = width * (bitsPerSample / 8);
                    Statistics[] rawStatistics = Statistics.FromBytes(
                        data, width, height, 1, bitsPerSample, stride, statisticsFormat);
                    if (rawStatistics == null || rawStatistics.Length == 0 || rawStatistics[0] == null)
                        continue;
 
                    var aggregate = new Statistics(bitsPerSample > 8);
                    aggregate.AddStatistics(rawStatistics[0]);
                    aggregate.MeanHistogram();
                    channelStatistics[sample] = aggregate;
                    imageStatistics.AddStatistics(rawStatistics[0]);
                    gotAnyStatistics = true;
                }
 
                if (channelStatistics.All(statistics => statistics != null))
                    image.Channels[channelIndex].stats = channelStatistics;
            }
 
            if (!gotAnyStatistics)
                return false;
 
            imageStatistics.MeanHistogram();
            image.Statistics = imageStatistics;
            return true;
        }

SampleZarrPixelAsync()

async Task< double?> BioGTK.SlideRenderer.SampleZarrPixelAsync	(	BioImage	image,
		ZCT	coordinate,
		int	pixelX,
		int	pixelY,
		CancellationToken	ct = default )

Definition at line 265 of file SlideRenderer.cs.

        {
            if (image?.IsZarrSource != true || pixelX < 0 || pixelY < 0 ||
                pixelX >= image.SizeX || pixelY >= image.SizeY)
                return null;
 
            List<ResolutionLevelNode> levels = await GetDirectZarrLevelsAsync(image, ct).ConfigureAwait(false);
            if (levels == null || levels.Count == 0)
                return null;
 
            var plane = await levels[0].ReadTileAsync(
                pixelX, pixelY, 1, 1,
                z: coordinate.Z,
                c: coordinate.C,
                t: coordinate.T,
                ct: ct).ConfigureAwait(false);
            byte[] data = plane?.Data;
            if (data == null || data.Length == 0)
                return null;
 
            PixelFormat format = image.Resolutions.Count > 0
                ? image.Resolutions[0].PixelFormat
                : PixelFormat.Format8bppIndexed;
            return format switch
            {
                PixelFormat.Format16bppGrayScale or PixelFormat.Format48bppRgb
                    when data.Length >= 2 => BitConverter.ToUInt16(data, 0),
                PixelFormat.Short when data.Length >= 2 => BitConverter.ToInt16(data, 0),
                PixelFormat.Float when data.Length >= 4 => BitConverter.ToSingle(data, 0),
                PixelFormat.UInt when data.Length >= 4 => BitConverter.ToUInt32(data, 0),
                _ => data[0]
            };
        }

SetSource() [1/2]

void BioGTK.SlideRenderer.SetSource

(

OpenSlideBase

source

)

Definition at line 84 of file SlideRenderer.cs.

        {
            ResetDirectZarrReader();
            _glArea.DiscardCompleteFrame();
            _openSlideBase = source;
            _slideBase = null;
            _useOpenSlide = true;
            _openTileCache = new OpenSlideGTK.TileCache(source, 200);
            ClearCache();
        }

SetSource() [2/2]

void BioGTK.SlideRenderer.SetSource

(

SlideBase

source

)

Definition at line 95 of file SlideRenderer.cs.

        {
            ResetDirectZarrReader();
            _glArea.DiscardCompleteFrame();
            _slideBase = source;
            _openSlideBase = null;
            _useOpenSlide = false;
            _tileCache = new BioLib.TileCache(source, 200);
            ClearCache();
        }

UpdateViewAsync()

async Task BioGTK.SlideRenderer.UpdateViewAsync	(	PointD	pyramidalOrigin,
		int	viewportWidth,
		int	viewportHeight,
		double	resolution,
		ZCT	coordinate )

Definition at line 374 of file SlideRenderer.cs.

        {
            if (_openSlideBase == null && _slideBase == null)
                return;
            if (viewportWidth <= 1 && viewportHeight <= 1)
                return;
 
            // Only allow one render pass at a time. Without this gate, rapid pan
            // events can pile up overlapping async tile fetches and keep large
            // byte[] buffers alive until every stale render finishes.
            if (!_renderSemaphore.Wait(0))
            {
                LastRenderSkipped = true;
                return;
            }
 
            LastRenderSkipped = false;
 
            try
            {
                int renderVersion = _renderStateVersion;
                int viewportVersion = _viewportVersion;
                CancellationTokenSource tileFetchCts;
                lock (_activeTileFetchLock)
                {
                    // This token represents render invalidation only. A timeout on a
                    // shared token would cancel every request in the batch after 60
                    // seconds, including tiles that were started much later. Each
                    // individual tile gets its own timeout in FetchTileAsync.
                    if (_activeTileFetchCts == null || _activeTileFetchCts.IsCancellationRequested)
                        _activeTileFetchCts = new CancellationTokenSource();
                    tileFetchCts = _activeTileFetchCts;
                }
 
            var schema = _useOpenSlide ? _openSlideBase.Schema : _slideBase.Schema;
 
            int level = TileUtil.GetLevel(schema.Resolutions, resolution);
            var levelRes = schema.Resolutions[level];
            double levelUnitsPerPixel = levelRes.UnitsPerPixel;
 
            await EnsureGlobalDisplayRangeAsync(coordinate, renderVersion, level).ConfigureAwait(false);
 
            bool levelChanged = level != _currentLevel;
 
            // Keep tile geometry for uploaded textures across viewport changes.
            // It lets pan/zoom immediately reproject the current pyramid level
            // while sharper tiles for a new level are still downloading. Entries
            // whose GPU textures were evicted are filtered by HasTileTexture.
 
            double originX = pyramidalOrigin.X;
            double originY = pyramidalOrigin.Y;
            double minX = originX;
            double width = viewportWidth * resolution;
            double height = viewportHeight * resolution;
            // BioLib pyramids use OSM-style inverted Y coordinates. Keep the
            // renderer in the same convention rather than trying to infer a
            // positive-down variant from the schema bounds.
            var viewportExtent = new Extent(minX, -originY - height, minX + width, -originY);
 
            // Keep the GL scissor aligned with the actual image boundary so
            // edge tiles don't leak padded black pixels outside the image.
            double imageMinX = schema.Extent.MinX;
            double imageMaxX = schema.Extent.MaxX;
            double imageMinY = schema.Extent.MinY;
            double imageMaxY = schema.Extent.MaxY;
            _glArea.ImageScreenX = (float)((imageMinX - pyramidalOrigin.X) / resolution);
            _glArea.ImageScreenY = (float)((-imageMaxY - pyramidalOrigin.Y) / resolution);
            _glArea.ImageScreenW = (float)((imageMaxX - imageMinX) / resolution);
            _glArea.ImageScreenH = (float)((imageMaxY - imageMinY) / resolution);
 
            // Prefetch one tile beyond each viewport edge so partially visible
            // edge tiles are available without overfetching an arbitrary 2x area.
            double tileMarginX = levelRes.TileWidth * levelUnitsPerPixel;
            double tileMarginY = levelRes.TileHeight * levelUnitsPerPixel;
            var fetchExtent = new Extent(
                viewportExtent.MinX - tileMarginX,
                viewportExtent.MinY - tileMarginY,
                viewportExtent.MaxX + tileMarginX,
                viewportExtent.MaxY + tileMarginY);
 
            List<TileInfo> tileInfos;
            List<TileInfo> fallbackInfos;
            if (_useOpenSlide)
            {
                // OpenSlide schemas use their historical pixel-space lookup path.
                var lookupExtent = BioLib.ExtentEx.WorldToPixelInvertedY(fetchExtent, levelUnitsPerPixel);
                tileInfos = schema.GetTileInfos(lookupExtent, level).ToList();
                fallbackInfos = schema.GetTileInfos(fetchExtent, level).ToList();
 
                if (fallbackInfos.Count > 0)
                {
                    var seen = new HashSet<TileIndex>(tileInfos.Select(t => t.Index));
                    foreach (var info in fallbackInfos)
                    {
                        if (seen.Add(info.Index))
                            tileInfos.Add(info);
                    }
                }
            }
            else
            {
                // BioLib/Zarr SlideBase schemas already use the same inverted-Y
                // world convention as BioLib's slice path. Keep lookups in that
                // space so translated datasets stay aligned with the tile schema.
                tileInfos = GetTileInfosIncludingBoundaries(schema, fetchExtent, level);
                fallbackInfos = new List<TileInfo>();
 
                if (tileInfos.Count == 0)
                {
                    var pixelToWorldExtent = BioLib.ExtentEx.PixelToWorldInvertedY(fetchExtent, levelUnitsPerPixel);
                    fallbackInfos = schema.GetTileInfos(pixelToWorldExtent, level).ToList();
 
                    if (fallbackInfos.Count == 0)
                    {
                        var worldToPixelExtent = BioLib.ExtentEx.WorldToPixelInvertedY(fetchExtent, levelUnitsPerPixel);
                        fallbackInfos = schema.GetTileInfos(worldToPixelExtent, level).ToList();
                    }
 
                    if (fallbackInfos.Count > 0)
                        tileInfos = fallbackInfos;
                }
            }
 
            var renderInfos = new List<TileRenderInfo>();
            var pendingFetches = new List<(TileInfo Tile, Task<byte[]> FetchTask)>();
            foreach (var tileInfo in tileInfos)
            {
                if (renderVersion != _renderStateVersion || viewportVersion != _viewportVersion)
                    return;
 
                var fetchTileInfo = tileInfo;
                var renderTileInfo = tileInfo;
 
                var renderInfo = CalculateScreenPosition(
                    renderTileInfo,
                    pyramidalOrigin,
                    resolution,
                    level,
                    schema);
                renderInfos.Add(renderInfo);
 
                if (!_glArea.HasTileTexture(fetchTileInfo.Index))
                {
                    bool alreadyPending;
                    lock (_pendingTileFetchLock)
                    {
                        alreadyPending = !_pendingTileFetches.Add(fetchTileInfo.Index);
                    }
 
                    if (!alreadyPending)
                        pendingFetches.Add((fetchTileInfo, FetchTileAsync(fetchTileInfo, level, coordinate, tileFetchCts.Token)));
                }
            }
 
            // Keep the visible target set resident even before it becomes the
            // displayed set. Otherwise FIFO eviction can continuously discard
            // newly uploaded target tiles and the level switch never completes.
            await RunOnGtkThreadAsync(() =>
                _glArea.SetProtectedTileIndices(renderInfos.Select(info => info.Index)))
                .ConfigureAwait(false);
 
            if (pendingFetches.Count > 0)
            {
                foreach (var pending in pendingFetches)
                    _ = ProcessPendingFetchAsync(pending.Tile, pending.FetchTask, tileFetchCts.Token, renderVersion, pyramidalOrigin, resolution, level, schema);
            }
 
            if (renderVersion != _renderStateVersion || viewportVersion != _viewportVersion)
                return;
 
            bool hasRenderableTexture = renderInfos.Any(tile => _glArea.HasTileTexture(tile.Index));
            if (levelChanged)
            {
                var fallbackRenderInfos = GetCachedLevelRenderInfos(
                    _currentLevel,
                    pyramidalOrigin,
                    resolution,
                    viewportWidth,
                    viewportHeight,
                    schema);
 
                if (hasRenderableTexture)
                {
                    bool canSwapNow = renderInfos.All(tile => _glArea.HasTileTexture(tile.Index));
                    if (canSwapNow)
                    {
                        _glArea.PreservePreviousFrameWhileIncomplete = false;
                        _glArea.ReleaseLevelTextures(_currentLevel);
                        _currentLevel = level;
                        lock (_pendingLevelSwitchLock)
                        {
                            _pendingLevelRenderInfos = null;
                            _pendingLevel = -1;
                            _pendingPreviousLevel = -1;
                        }
                    }
                    else
                    {
                        _glArea.PreservePreviousFrameWhileIncomplete = true;
                        lock (_pendingLevelSwitchLock)
                        {
                            _pendingLevelRenderInfos = new List<TileRenderInfo>(renderInfos);
                            _pendingLevel = level;
                            _pendingPreviousLevel = _currentLevel;
                        }
                        await ShowImmediateZoomFallbackAsync(fallbackRenderInfos).ConfigureAwait(false);
                        return;
                    }
                }
                else
                {
                    _glArea.PreservePreviousFrameWhileIncomplete = true;
                    lock (_pendingLevelSwitchLock)
                    {
                        _pendingLevelRenderInfos = new List<TileRenderInfo>(renderInfos);
                        _pendingLevel = level;
                        _pendingPreviousLevel = _currentLevel;
                    }
                    await ShowImmediateZoomFallbackAsync(fallbackRenderInfos).ConfigureAwait(false);
                    return;
                }
            }
 
            if (renderVersion != _renderStateVersion || viewportVersion != _viewportVersion)
                return;
 
            await RunOnGtkThreadAsync(() =>
            {
                _glArea.SetTilesToRender(renderInfos);
                _glArea.RequestRedraw();
            });
            }
            catch (OperationCanceledException)
            {
                // Cancellation is normal when a source closes or display state is
                // replaced. Never let it fault the fire-and-forget UI render task.
            }
            finally
            {
                _renderSemaphore.Release();
 
                if (LastRenderSkipped)
                {
                    LastRenderSkipped = false;
                    Gtk.Application.Invoke((s, a) => App.viewer?.RequestDeferredRender());
                }
            }
        }

Property Documentation

CachedTextureCount

int BioGTK.SlideRenderer.CachedTextureCount

get

Definition at line 1332 of file SlideRenderer.cs.

        {
            get
            {
                lock (_uploadedTileLock)
                    return _uploadedTiles.Count;
            }
        }

CurrentLevel

int BioGTK.SlideRenderer.CurrentLevel

get

Definition at line 1331 of file SlideRenderer.cs.

LastRenderSkipped

bool BioGTK.SlideRenderer.LastRenderSkipped

get

Definition at line 43 of file SlideRenderer.cs.

{ get; private set; }

---

The documentation for this class was generated from the following file:

• BioGTK/BioGTK/Source/SlideRenderer.cs