Iris Core API Documentation. More...

#include <stdint.h>
#include <vector>
#include <map>
#include <unordered_map>
#include <thread>
#include <shared_mutex>
#include <functional>
#include "IrisTypes.hpp"

Functions
int	Iris::get_major_version ()
	Get the major version of Iris within the binaries.

int	Iris::get_minor_version ()
	Get the minor version of Iris within the binaries.

int	Iris::get_build_number ()
	Get the build number of these binaries.

Viewer	Iris::create_viewer (const ViewerCreateInfo &) noexcept
	Create an Iris viewer instance.

Result	Iris::viewer_bind_external_surface (const ViewerBindExternalSurfaceInfo &) noexcept
	Bind a viewer to an external surface controlled by the calling application.

Result	Iris::viewer_unbind_surface (const Viewer &viewer) noexcept
	Unbind the external drawing surface controlled by the calling application.

Result	Iris::viewer_window_resized (const Viewer &viewer) noexcept
	Inform a viewer that the attached window was resized.

Result	Iris::viewer_open_slide (const Viewer &viewer, const SlideOpenInfo &info) noexcept
	Create and open a slide for viewing.

Result	Iris::viewer_close_slide (const Viewer &viewer) noexcept
	Close the current slide being viewed by the viewer.

Result	Iris::viewer_engine_translate (const Viewer &viewer, const ViewerTranslateScope &) noexcept
	Translate the scope view when rendering a whole slide image.

Result	Iris::viewer_engine_zoom (const Viewer &viewer, const ViewerZoomScope &) noexcept
	Change the scope view amound when rending a whole slide image.

Result	Iris::viewer_annotate_slide (const Viewer &viewer, const SlideAnnotation &) noexcept
	Insert an image slide annotation into the current active slide at the location within the screen.

Slide	Iris::create_slide (const SlideOpenInfo &info)
	Create an Iris::Slide object encapsulating access to a whole slide image object.

Buffer	Iris::Create_strong_buffer ()
	Create a strong buffer but without memory backing.

Buffer	Iris::Create_strong_buffer (size_t buffer_size_in_bytes)
	Create a strong blank buffer with an initial capacity of buffer_size_in_bytes bytes long.

Buffer	Iris::Copy_strong_buffer_from_data (const void *data_ptr, size_t bytes)
	Create a strong buffer and copy the data pointed to by dataptr and bytes in length (in bytes).

Buffer	Iris::Wrap_weak_buffer_fom_data (const void *const data_ref, size_t bytes)
	Wrap a weak buffer around foreign data. This wrapper is used for implementing Iris Codec functions on foreign data blocks without having to copy the data.

void *	Iris::Buffer_write_into_buffer (const Buffer &buffer, size_t bytes)
	Write data into a buffer in a safe manner.

void	Iris::Buffer_get_data (const Buffer &buffer, void *&data, size_t &bytes)
	Copy-extract the data from the underlying buffer structure.

void	Iris::Buffer_change_strength (const Buffer &buffer, BufferReferenceStrength strength)
	Change the strength of an Iris Buffer.

Detailed Description

Iris Core API Documentation.

Author: Ryan Landvater

Version: 2024.0.3

Date: 2024-08-26

Copyright: Copyright (c) 2023-24 Created by Ryan Landvater on 8/26/23.

Function Documentation

◆ Buffer_change_strength()

void Iris::Buffer_change_strength	(	const Buffer &	buffer,
		BufferReferenceStrength	strength )

Change the strength of an Iris Buffer.

Parameters

buffer	handle to the buffer object. Must be a valid buffer.
strength	strength to assign the buffer

See also: BufferReferenceStrength for more details

◆ Buffer_get_data()

void Iris::Buffer_get_data	(	const Buffer &	buffer,
		void *&	data,
		size_t &	bytes )

Copy-extract the data from the underlying buffer structure.

This is useful if you don't want to include the IrisCodecBuffer.h header and expose yourself to accidentally using it incorrectly and corrupting your memory.

Parameters

buffer	Iris::Buffer handle
data	data pointer to copy the data into. If a null-ptr, only the size will be returned.
bytes	number of bytes copied out of the buffer handle

◆ Buffer_write_into_buffer()

void * Iris::Buffer_write_into_buffer	(	const Buffer &	buffer,
		size_t	bytes )

Write data into a buffer in a safe manner.

This is useful if you don't want to include the IrisCodec_buffer.h header and expose yourself to accidentally using it wrong and corrupting your data. This function works like a c-style array exposed to a method for writing. Provide the buffer and size. This method functions differently based upon the strength of the reference (see discussion below)

If the reference is STRONG, this method will expose the begining of the next writable segment and will expand the buffer if there is insufficient space. The buffer's internal size metric will reflect the new data.

Warning: If the reference is weak and if there is insufficient space within the bufferthis will throw an exception (as weak buffer wrappers are not permitted to expand a buffer). If you are worried about a buffer overflow, you may consider strengthening the buffer reference to allow for expansion.

Parameters

buffer	Iris::Buffer handle
bytes	number of bytes to prepare for writing; size of the buffer will be expanded by this number of bytes

Returns: void* c-style data pointer to start writable memory (to populate with memcopy for example); NULL-pointer in the event of failure.

◆ Copy_strong_buffer_from_data()

Buffer Iris::Copy_strong_buffer_from_data	(	const void *	data_ptr,
		size_t	bytes )

Create a strong buffer and copy the data pointed to by dataptr and bytes in length (in bytes).

This is copy constructable and will maintain the life of the underlying data (once allocated) as long as one copy persists. The data pointed to by dataptr will be copied into the returned buffer and the data source can be safely freed at any time.

Parameters

data_ptr	pointer to raw bytes to be copied into the new buffer
bytes	number of bytes to copy into the buffer. This will be resulting buffer size.

Returns: Valid Iris::Buffer handle on success; Nullptr on failure

◆ create_slide()

Slide Iris::create_slide ( const SlideOpenInfo & info )

Create an Iris::Slide object encapsulating access to a whole slide image object.

The Slide object has a variety of interal functionalities in addition to mapping the WSI file. This includes asynchronous non-blocking read threads that load the slide tile image data.

Note: Iris::viewer_open_slide(const Viewer& viewer, const Slide&) is the preferred method as it allows the Iris Render Engine to configure optional performance parameters.

Parameters

info	Iris::SlideOpenInfo structure

Returns: Valid Iris::Slide handle on success; Nullptr on failure

◆ Create_strong_buffer() [1/2]

Buffer Iris::Create_strong_buffer ( )

Create a strong buffer but without memory backing.

This is copy constructable and will maintain the life of the underlying data (once allocated) as long as one copy persists. Configure the memory backing afterwards by expanding the data block.
This function will construct a strong buffer object with 'capacity' and 'size' of 0-bytes,

Note: Despite being a strong buffer, there is no owned data block yet. It must be initialized first.

Returns: Valid Iris::Buffer handle on success but without data block backing.; Nullptr on failure

◆ Create_strong_buffer() [2/2]

Buffer Iris::Create_strong_buffer ( size_t buffer_size_in_bytes )

Create a strong blank buffer with an initial capacity of buffer_size_in_bytes bytes long.

This is copy constructable and will maintain the life of the underlying data (once allocated) as long as one copy persists. The size will be 0, despite the capacity being defined.

Parameters

buffer_size_in_bytes the initial capacity (in bytes). The internal 'size' is '0' bytes

Returns: Valid Iris::Buffer handle with size 0 bytes on success; Nullptr on failure

◆ create_viewer()

Viewer Iris::create_viewer ( const ViewerCreateInfo & )

noexcept

Create an Iris viewer instance.

The viewer is the primary interface between the whole slide rendering system and the calling application that is using Iris to draw slide views. Use the below viewer_bind_external_surface to bind and initialize the system.

Note: This function only creates the viewer. It does not initialize it. The viewer must be bound to an application surface generated by the operating system before it can be used.

Returns: Valid Viewer handle on success; Nullptr on failure

◆ get_build_number()

int Iris::get_build_number ( )

Get the build number of these binaries.

Returns: int build number.

◆ get_major_version()

int Iris::get_major_version ( )

Get the major version of Iris within the binaries.

Returns: int major version

◆ get_minor_version()

int Iris::get_minor_version ( )

Get the minor version of Iris within the binaries.

Returns: int minor version

◆ viewer_annotate_slide()

Result Iris::viewer_annotate_slide	(	const Viewer &	viewer,
		const SlideAnnotation &	)

noexcept

Insert an image slide annotation into the current active slide at the location within the screen.

Parameters

viewer Iris::Viewer handle

◆ viewer_bind_external_surface()

Result Iris::viewer_bind_external_surface ( const ViewerBindExternalSurfaceInfo & )

noexcept

Bind a viewer to an external surface controlled by the calling application.

Unbind the viewer before destroying the view or allow the viewer to exit scope and it will automatically unbind the surface.

Note: The provided surface must outlive the viewer once bound. If the viewer should outlive the surface, the viewer can be unbound via viewer_unbind_surface (const Viewer&);

Returns: true when the system has sucessfully configured; false when the system failed to effectively configure.

◆ viewer_close_slide()

Result Iris::viewer_close_slide ( const Viewer & viewer )

noexcept

Close the current slide being viewed by the viewer.

Parameters

viewer Iris::Viewer handle

◆ viewer_engine_translate()

Result Iris::viewer_engine_translate	(	const Viewer &	viewer,
		const ViewerTranslateScope &	)

noexcept

Translate the scope view when rendering a whole slide image.

Parameters

viewer Iris::Viewer handle

◆ viewer_engine_zoom()

Result Iris::viewer_engine_zoom	(	const Viewer &	viewer,
		const ViewerZoomScope &	)

noexcept

Change the scope view amound when rending a whole slide image.

Parameters

viewer Iris::Viewer handle

◆ viewer_open_slide()

Result Iris::viewer_open_slide	(	const Viewer &	viewer,
		const SlideOpenInfo &	info )

noexcept

Create and open a slide for viewing.

This will close any currently opened slide within the viewer and attempt to open a new slide using the file information defined within Iris::SlideOpenInfo structure. Use the Iris::viewer_open_slide(const Iris::Viewer&, const Iris::Slide&) function if there is already an active Iris::Slide object opened via Iris::create_slide(const Iris::SlideOpenInfo&) call with valid info;

Parameters

viewer	Iris::Viewer handle
info	slide file information

◆ viewer_unbind_surface()

Result Iris::viewer_unbind_surface ( const Viewer & viewer )

noexcept

Unbind the external drawing surface controlled by the calling application.

Note: For objective-C implementations, this will break the ARC loop and allow the proper program breakdown

Parameters

viewer Iris::Viewer handle

◆ viewer_window_resized()

Result Iris::viewer_window_resized ( const Viewer & viewer )

noexcept

Inform a viewer that the attached window was resized.

This will force a reconstruction of the viewer rendering engine's swapchain to accomodate the new window size. It will also resize any optional UI scene object locations / R-tree orderings.

Parameters

viewer Iris::Viewer handle

◆ Wrap_weak_buffer_fom_data()

Buffer Iris::Wrap_weak_buffer_fom_data	(	const void *const	data_ref,
		size_t	bytes )

Wrap a weak buffer around foreign data. This wrapper is used for implementing Iris Codec functions on foreign data blocks without having to copy the data.

This is a convenience function for such tasks as decoding network derived large buffers sequences to reduce data copy and redundancy. Weak buffers can become strong should it be required. Doing so will force the buffer to adopt responsibility for freeing the underlying data ** and may change or invalidate the pointer** to the underlying data should it need to expand the block.

Note: This buffer has no ownership over the underlying data and the underlying data must persist while the buffer is used.; The buffer can switch ownership to strong but doing so may invalidate the origianl data_ref.

Returns: Valid Iris::Buffer (weak ownership) handle on success; Nullptr on failure

Functions

Detailed Description

Function Documentation

◆ Buffer_change_strength()

◆ Buffer_get_data()

◆ Buffer_write_into_buffer()

◆ Copy_strong_buffer_from_data()

◆ create_slide()

◆ Create_strong_buffer() [1/2]

◆ Create_strong_buffer() [2/2]

◆ create_viewer()

◆ get_build_number()

◆ get_major_version()

◆ get_minor_version()

◆ viewer_annotate_slide()

◆ viewer_bind_external_surface()

◆ viewer_close_slide()

◆ viewer_engine_translate()

◆ viewer_engine_zoom()

◆ viewer_open_slide()

◆ viewer_unbind_surface()

◆ viewer_window_resized()

◆ Wrap_weak_buffer_fom_data()