Skip to content

Event documentation - #507

Open
frasercl wants to merge 4 commits into
feature/load-eventsfrom
feat/event-docs
Open

frasercl wants to merge 4 commits into
feature/load-eventsfrom
feat/event-docs

Conversation

@frasercl

@frasercl frasercl commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Resolves #471: documents all the events fired by View3d/Volume. Docs include links where relevant.

@frasercl
frasercl requested a review from a team as a code owner November 6, 2026 02:13
@frasercl
frasercl requested review from ShrimpCryptid and removed request for a team November 6, 2026 02:13
@frasercl
frasercl added this pull request to stack #500 November 6, 2026 02:19
@frasercl frasercl changed the title Feat/event docs Event documentation Nov 6, 2026

@ShrimpCryptid ShrimpCryptid left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@ShrimpCryptid ShrimpCryptid linked an issue Nov 10, 2026 that may be closed by this pull request
@frasercl
frasercl requested review from toloudis and a balanced review from Copilot November 13, 2026 19:46

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Event documentation misstates callback timing, load completion scope, and payload guarantees, while the loadEnd typing example produces a TypeScript error.

4 open issues
What changed in this PR

This PR addresses #471 by documenting the events exposed by View3d and Volume, helping vole-core consumers discover subscriptions and payload types.

Changes:

  • Adds event descriptions, payload documentation, and type lookup examples.
  • Expands View3d documentation with canvas setup and volume usage guidance.
  • Exports View3dEvents and EventDispatcher through the package entry point.
File Description
src/​Volume.ts Documents volume events and their payloads.
src/​View3d.ts Documents viewer setup and rendering events; exports View3dEvents.
src/​index.ts Exposes View3dEvents and EventDispatcher to package consumers.

Review effort: Balanced

Comment thread src/View3d.ts
Comment on lines +85 to +90
* `View3d` is an {@linkcode EventDispatcher}. It fires the following events in response to canvas renders:
* - `render` is fired when the canvas re-renders for any reason, including camera moves, settings changes, data loads,
* etc. It has no payload.
* - `renderIteration` is fired when the canvas renders in response to *either a render mode change or a new iteration
* of the progressive path trace renderer*. It is useful for tracking the current path trace iteration count. Its
* payload contains the following properties:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I sort of agree with the ai review here -- if nothing else, for clarity and accuracy. I wouldn't specifically say on resets to 0 but I'd describe anything that causes the pathtrace to reset, such as camera moves or lighting changes or any appearance change.

Comment thread src/Volume.ts
/**
* The map of all events fired by {@linkcode Volume}. See its documentation for details of event behavior.
*
* Retrieve the payload of a specific event using brackets and the event name, like so: `View3dEvents["loadEnd"]`.
Comment thread src/Volume.ts
* {@linkcode load} or automatic loads triggered by settings changes like time point, enabled channels, etc.
* - `loadChannel` is fired when a specific channel has finished loading. Its payload contains the numeric property
* `channelIndex` that indicates the specific channel to which it applies.
* - `loadEnd` is fired when all channels in the `Volume` have finished loading.
Comment thread src/Volume.ts
Comment on lines +48 to +49
* In addition to any payload specified above, all events include the property `volume`, which points to the `Volume`
* that fired the event.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👀

@toloudis toloudis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I recommend some shuffling and if the ai review is correct, then need to make a few of the comments be a bit more accurate to what the implementation does.

Comment thread src/View3d.ts
*
* Once you've created a `View3d`, use {@linkcode addVolume}/{@linkcode removeVolume} to add/remove an image to render.
*
* Most other methods on `View3d` set rendering options or options on the current image.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe instead of "current" image, the "specified" image, since on all these methods, you pass a Volume in, right?

Comment thread src/View3d.ts
Comment on lines +85 to +90
* `View3d` is an {@linkcode EventDispatcher}. It fires the following events in response to canvas renders:
* - `render` is fired when the canvas re-renders for any reason, including camera moves, settings changes, data loads,
* etc. It has no payload.
* - `renderIteration` is fired when the canvas renders in response to *either a render mode change or a new iteration
* of the progressive path trace renderer*. It is useful for tracking the current path trace iteration count. Its
* payload contains the following properties:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I sort of agree with the ai review here -- if nothing else, for clarity and accuracy. I wouldn't specifically say on resets to 0 but I'd describe anything that causes the pathtrace to reset, such as camera moves or lighting changes or any appearance change.

Comment thread src/View3d.ts
* etc. It has no payload.
* - `renderIteration` is fired when the canvas renders in response to *either a render mode change or a new iteration
* of the progressive path trace renderer*. It is useful for tracking the current path trace iteration count. Its
* payload contains the following properties:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest moving the descriptions of these events up to the type where they are defined, View3dEvents, as comments above each event type's name

Comment thread src/Volume.ts
* - `channelAdded` is fired when a new channel is added to the `Volume`. Its payload contains the property
* `channelIndex` containing the numeric index of the added channel.
* - `channelRemoved` is fired when a channel is removed from the `Volume`. Its payload contains the property
* `channelIndex` containing the numeric index of the removed channel.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

move these descriptions up to their respective rows in VolumeEvents and refer to VolumeEvents in this comment?

Comment thread src/Volume.ts
Comment on lines +48 to +49
* In addition to any payload specified above, all events include the property `volume`, which points to the `Volume`
* that fired the event.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👀

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document all EventDispatchers

4 participants