AcademySoftwareFoundation / AcademySoftwareFoundation/OpenImageIO

[BUG] Writing ImageIO Plugins section does not describe how to register a plug-in at run time

Open
#3,099 6 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
2.4k
Forks
698
Avg merge
3d 9h
Merged PRs (30d)
48

Description

**Describe the bug**
The _Writing ImageIO Plugins_ section of the documentation does not describe how to register the plug-in at run time.

**To Reproduce**
Steps to reproduce the behavior:
1. Read the documentation section and observe that all it states is you have to write a subclass of ImageInput or ImageOutput and documents various methods you must implement.

**Expected behavior**
Given all the talk about being able to add plugins without modifying OpenImageIO I expected this section to describe exactly and completely how to do so.

Having spent more time browsing the documentation I found the function `OIIO::declare_imageio_format` which takes `ImageInput::Creator` and `ImageOutput::Creator` pointers. What the `Creators` should point to is not clear. One can surmise that they are the `name_{input,output}_imageio_create` methods mentioned in ˆWriting ImageIO Plugins`.

Another question whose answer would be welcome is what happens if the format name of plugin you declare has the same name as an existing plug-in. Will it replace the existing one?

**Evidence**
n/a

**Platform information:**
n/a

Contributor guide

Open the contributing guide

Research direction

Start with the Writing ImageIO Plugins documentation section and the OIIO::declare_imageio_format API mentioned in the issue. Clarify how ImageInput::Creator and ImageOutput::Creator are used at runtime, and document behavior when a declared format name conflicts with an existing plugin. Done means the section answers these registration and duplicate-name questions.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.