From af85e80d918481db2dd743728f7cdf0796751e55 Mon Sep 17 00:00:00 2001 From: John-Paul Smith Date: Wed, 10 Jul 2024 11:09:40 +0100 Subject: [PATCH] Improvements to the docs and OCIO config To aid with versioning, the OFX OCIO config has been renamed, now including the OpenFX version number instead of the version number of the upstream OCIO config. Basic colourspaces have been removed from the reference OCIO config, allowing hosts and plug-ins to freely choose any colourspace with the correct attributes. Two colourspaces were missing from the core style and have been added. Various doc improvements to fix typos and make the intended usage clearer. Signed-off-by: John-Paul Smith --- include/ofxColour.h | 41 +++++++--- include/ofxColourspaceList.h | 81 ++++++++++--------- ...enfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio} | 7 +- scripts/genColour | 21 +++-- scripts/genOCIOConfig | 13 +-- 5 files changed, 88 insertions(+), 75 deletions(-) rename include/{openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3.ocio => openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio} (99%) diff --git a/include/ofxColour.h b/include/ofxColour.h index 5b8b10cc..594757f6 100644 --- a/include/ofxColour.h +++ b/include/ofxColour.h @@ -33,9 +33,13 @@ colour management. OCIO is used as the reference for the colour management API, but is not required to implement the native styles. The colourspace strings used in the native styles are from -openfx-studio-config-v2.1.0_acces-v1.3_ocio-v2.3.ocio -and stored for OFX purposes in ofxColourspaceList.h. Additionally, there is -a scheme for cross-referencing between clips. +openfx-native-1.5.ocio, which is based on the OCIO ACES Studio built-in +config, studio-config-v2.1.0_aces-v1.3_ocio-v2.3, and stored for OFX purposes +in ofxColourspaceList.h. Additionally, there is a scheme for cross-referencing +between clips, and a set of "basic colourspaces", which are designed to be +generic names for a family of colourspaces. When a basic colourspace is used, +this means the host is free to choose any colourspace with the same encoding +and reference space (scene vs display). The assumption is that OCIO > Full > Core > Basic, so the highest style supported by both host and plug-in will be chosen. @@ -63,10 +67,19 @@ A host must set this property on any effect instances where it has negotiated OCIO colour management (kOfxImageEffectPropColourManagementOCIO). Use of URIs for built-in configs, such as ocio://default is permitted. -When native colour management is in use, a host must set this -property to point to the OCIO config used to define strings for the version of -OFX it was built against. This will allow a plug-in which uses OCIO to work -directly with native styles. +When the core or full styles are in use, a host must set this property to +point to an OCIO config which defines all the colourspaces required for that +style, which will allow a plug-in that uses OCIO to work directly with native +styles. The included config, openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio, is +suitable, but hosts might provide a different config which is compatible. If +hosts choose to use their own config, its definitions for native colourspaces +must exactly match those found in openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio. + +As basic colourspaces are not defined in the OpenFX native config, hosts may +set this property as they wish when using the basic style. If hosts do provide +a config, an OCIO-based plug-in may attempt to use it to look up mappings for +basic colourspaces, but leaving those undefined must not be considered an +error. */ #define kOfxImageEffectPropOCIOConfig "OfxImageEffectPropOCIOConfig" @@ -81,8 +94,8 @@ it will be set to the working colourspace of the host but could be any valid colourspace. Plug-ins may set this property on an output clip. Plug-ins which output motion -vectors or similar images which should not be colour managed can use the data -colourspace which is present in the built-in OCIO configs. +vectors or similar images which should not be colour managed should use +kOfxColourspaceRaw, Both host and plug-in should use the value of kOfxImageClipPropPreferredColourspace where reasonable. @@ -90,7 +103,9 @@ kOfxImageClipPropPreferredColourspace where reasonable. Cross-referencing between clips is possible by setting this property to "OfxColourspace_". For example a plug-in may set this property on its output clip to "OfxColourspace_Source", telling the host that the colourspace -of the output matches the input. +of the output matches the input. In the basic style, plug-ins are recommended +to use cross-referencing for their output clip unless kOfxColourspaceRaw is +required. If a clip sets OfxImageClipPropIsMask or it only supports OfxImageComponentAlpha, colour management is disabled and this property @@ -122,8 +137,8 @@ The host is free to choose any colourspace from this list, but should favour the first mutually agreeable colourspace, and set kOfxImageClipPropColourspace to tell the plug-in which colourspace has been selected. A host does not need to convert into the first choice just because it can, as this might be -inefficient, and should scene-to-display or display-to-scene conversions where -possible. +inefficient, and should avoid scene-to-display or display-to-scene conversions +where possible. In the event that the host cannot supply images in a requested colourspace, it may supply images in any valid colourspace. Plug-ins must check @@ -147,7 +162,7 @@ both input clips to be in the same colourspace. A host might set the same thing on the plug-in's output clip to request that the plug-in outputs the same colourspace as the input. -If a plug-in has inputs which contain motion vectors, depth values or other +If a plug-in has inputs which expect motion vectors, depth values or other non-colour channels, it should set the preferred colourspace to kOfxColourspaceRaw. Similarly, if a host requests outputs in a typical scene colourspace, but the plug-in is producing motion vectors, it should ignore diff --git a/include/ofxColourspaceList.h b/include/ofxColourspaceList.h index 5830ed5b..014fee8e 100644 --- a/include/ofxColourspaceList.h +++ b/include/ofxColourspaceList.h @@ -10,11 +10,12 @@ extern "C" { /** @file ofxColourspaceList.h Contains the list of supported colourspaces. -This file was auto-generated by scripts/genColour from openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3. +This file was auto-generated by scripts/genColour from openfx-native-v1.5_aces-v1.3_ocio-v2.3. */ // Basic Colourspaces +// These colourspaces are generic names for any colourspace with the correct attributes. /** @brief ofx_hdr Any display-referred HDR video such as Rec. 2020 HLG or PQ. @@ -39,7 +40,7 @@ Any scene-referred linear colourspace. #define kOfxColourspaceOfxLinearIsDisplay false /** @brief ofx_log -Any colourspace with a log transfer function. +Any scene-referred colourspace with a log transfer function. */ #define kOfxColourspaceOfxLog "ofx_log" #define kOfxColourspaceOfxLogLabel "ofx_log" @@ -169,6 +170,43 @@ Any display-referred SDR video such as Rec. 709. #define kOfxColourspaceRec2100PqDisplayIsCore true #define kOfxColourspaceRec2100PqDisplayIsDisplay true +// st2084_p3d65_display +// Convert CIE XYZ (D65 white) to ST-2084 (PQ), P3-D65 primaries +// AMF Components +// -------------- +// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_1000nits_15nits_ST2084.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_1000nits_15nits_ST2084.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_2000nits_15nits_ST2084.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_2000nits_15nits_ST2084.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_4000nits_15nits_ST2084.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_4000nits_15nits_ST2084.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_108nits_7point2nits_ST2084.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_108nits_7point2nits_ST2084.a1.1.0 +#define kOfxColourspaceSt2084P3d65Display "st2084_p3d65_display" +#define kOfxColourspaceSt2084P3d65DisplayLabel "ST2084-P3-D65 - Display" +#define kOfxColourspaceSt2084P3d65DisplayEncoding "hdr-video" +#define kOfxColourspaceSt2084P3d65DisplayIsData false +#define kOfxColourspaceSt2084P3d65DisplayIsBasic false +#define kOfxColourspaceSt2084P3d65DisplayIsCore true +#define kOfxColourspaceSt2084P3d65DisplayIsDisplay true + +// p3d65_display +// Convert CIE XYZ (D65 white) to Gamma 2.6, P3-D65 +// AMF Components +// -------------- +// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_48nits.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvODT.Academy.P3D65_48nits.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_Rec709limited_48nits.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_D60sim_48nits.a1.1.0 +// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvODT.Academy.P3D65_D60sim_48nits.a1.1.0 +#define kOfxColourspaceP3d65Display "p3d65_display" +#define kOfxColourspaceP3d65DisplayLabel "P3-D65 - Display" +#define kOfxColourspaceP3d65DisplayEncoding "sdr-video" +#define kOfxColourspaceP3d65DisplayIsData false +#define kOfxColourspaceP3d65DisplayIsBasic false +#define kOfxColourspaceP3d65DisplayIsCore true +#define kOfxColourspaceP3d65DisplayIsDisplay true + // ACES2065-1 // The "Academy Color Encoding System" reference colorspace. #define kOfxColourspaceACES20651 "ACES2065-1" @@ -342,26 +380,6 @@ Any display-referred SDR video such as Rec. 709. #define kOfxColourspaceCIEXYZD65IsCore false #define kOfxColourspaceCIEXYZD65IsDisplay true -// st2084_p3d65_display -// Convert CIE XYZ (D65 white) to ST-2084 (PQ), P3-D65 primaries -// AMF Components -// -------------- -// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_1000nits_15nits_ST2084.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_1000nits_15nits_ST2084.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_2000nits_15nits_ST2084.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_2000nits_15nits_ST2084.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_4000nits_15nits_ST2084.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_4000nits_15nits_ST2084.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_108nits_7point2nits_ST2084.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_108nits_7point2nits_ST2084.a1.1.0 -#define kOfxColourspaceSt2084P3d65Display "st2084_p3d65_display" -#define kOfxColourspaceSt2084P3d65DisplayLabel "ST2084-P3-D65 - Display" -#define kOfxColourspaceSt2084P3d65DisplayEncoding "hdr-video" -#define kOfxColourspaceSt2084P3d65DisplayIsData false -#define kOfxColourspaceSt2084P3d65DisplayIsBasic false -#define kOfxColourspaceSt2084P3d65DisplayIsCore false -#define kOfxColourspaceSt2084P3d65DisplayIsDisplay true - // p3d60_display // Convert CIE XYZ (D65 white) to Gamma 2.6, P3-D60 (Bradford adaptation) // AMF Components @@ -376,23 +394,6 @@ Any display-referred SDR video such as Rec. 709. #define kOfxColourspaceP3d60DisplayIsCore false #define kOfxColourspaceP3d60DisplayIsDisplay true -// p3d65_display -// Convert CIE XYZ (D65 white) to Gamma 2.6, P3-D65 -// AMF Components -// -------------- -// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_48nits.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvODT.Academy.P3D65_48nits.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_Rec709limited_48nits.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_D60sim_48nits.a1.1.0 -// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvODT.Academy.P3D65_D60sim_48nits.a1.1.0 -#define kOfxColourspaceP3d65Display "p3d65_display" -#define kOfxColourspaceP3d65DisplayLabel "P3-D65 - Display" -#define kOfxColourspaceP3d65DisplayEncoding "sdr-video" -#define kOfxColourspaceP3d65DisplayIsData false -#define kOfxColourspaceP3d65DisplayIsBasic false -#define kOfxColourspaceP3d65DisplayIsCore false -#define kOfxColourspaceP3d65DisplayIsDisplay true - // p3_dci_display // Convert CIE XYZ (D65 white) to Gamma 2.6, P3-DCI (DCI white with Bradford adaptation) // AMF Components @@ -784,7 +785,7 @@ A colourspace suitable for colour grading, typically a log colourspace. #define kOfxColourspaceRoleColorTiming "color_timing" /** @brief compositing_log -Any colourspace with a log transfer function. +Any scene-referred colourspace with a log transfer function. */ #define kOfxColourspaceRoleCompositingLog "compositing_log" diff --git a/include/openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3.ocio b/include/openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio similarity index 99% rename from include/openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3.ocio rename to include/openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio index 0771baea..dece8ee7 100644 --- a/include/openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3.ocio +++ b/include/openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio @@ -5,7 +5,7 @@ environment: search_path: "" strictparsing: true luma: [0.2126, 0.7152, 0.0722] -name: openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3 +name: openfx-native-v1.5_aces-v1.3_ocio-v2.3 description: | OpenFX 1.5 Native Mode Config Based on: Academy Color Encoding System - Studio Config [COLORSPACES v2.1.0] [ACES v1.3] [OCIO v2.3] @@ -21,11 +21,6 @@ roles: compositing_log: ACEScct data: Raw matte_paint: ACEScct - ofx_hdr: Rec.2100-HLG - Display - ofx_linear: ACEScg - ofx_log: ACEScct - ofx_raw: Raw - ofx_sdr: Rec.1886 Rec.709 - Display scene_linear: ACEScg texture_paint: sRGB - Texture diff --git a/scripts/genColour b/scripts/genColour index 4eb28c6a..d302c787 100755 --- a/scripts/genColour +++ b/scripts/genColour @@ -5,7 +5,7 @@ # Extract information from an OCIO config to C header. # Example invocation: -# OCIO=include/openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3.ocio scripts/genColour > include/ofxColourspaceList.h +# OCIO=include/openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio scripts/genColour > include/ofxColourspaceList.h import sys import PyOpenColorIO as OCIO @@ -38,14 +38,14 @@ footer = ''' role_docs = { 'ofx_sdr': 'Any display-referred SDR video such as Rec. 709.', 'ofx_hdr': 'Any display-referred HDR video such as Rec. 2020 HLG or PQ.', - 'ofx_log': 'Any colourspace with a log transfer function.', + 'ofx_log': 'Any scene-referred colourspace with a log transfer function.', 'ofx_linear': 'Any scene-referred linear colourspace.', 'ofx_raw': 'Image values should not be treated as colour, e.g. motion vectors or masks.', 'aces_interchange': 'Guaranteed to be ACES2065-1.', 'cie_xyz_d65_interchange': 'CIE XYZ colorimetry with the neutral axis at D65.', 'color_picking': 'The colourspace to use for colour pickers, typically a display colourspace.', 'color_timing': 'A colourspace suitable for colour grading, typically a log colourspace.', - 'compositing_log': 'Any colourspace with a log transfer function.', + 'compositing_log': 'Any scene-referred colourspace with a log transfer function.', 'data': 'Image values should not be treated as colour, e.g. motion vectors or masks. Mapped to the raw colourspace.', 'matte_paint': 'A colourspace suitable for matte painting.', 'scene_linear': 'Any scene-referred linear colourspace.', @@ -117,14 +117,25 @@ core_spaces = ['srgb_display', 'displayp3_display', 'rec1886_rec709_display', 'lin_rec709_srgb', 'g18_rec709_tx', 'g22_ap1_tx', 'g22_rec709_tx', 'g24_rec709_tx', 'srgb_encoded_ap1_tx', 'srg_encoded_p3d65_tx', 'srgb_tx', 'Raw', - 'rec1886_rec2020_display', 'rec2100_hlg_display', 'rec2100_pq_display'] + 'rec1886_rec2020_display', 'rec2100_hlg_display', 'rec2100_pq_display', + 'st2084_p3d65_display', 'p3d65_display'] # This should be the OpenFX OCIO config created by genOCIOConfig ofx_config = OCIO.GetCurrentConfig() +# Add OFX-specific basic colourspaces here rather than in genOCIOConfig +# to avoid creating an expectation that these mappings should always be used. +# The assigned colourspaces are chosen simply to generate the correct +# attributes in the header. +ofx_config.setRole('ofx_sdr', 'rec1886_rec709_display') +ofx_config.setRole('ofx_hdr', 'rec2100_hlg_display') +ofx_config.setRole('ofx_log', 'ACEScct') +ofx_config.setRole('ofx_linear', 'ACEScg') +ofx_config.setRole('ofx_raw', 'raw') + print(Template(header).substitute(config_name=ofx_config.getName())) -print('\n// Basic Colourspaces') +print('\n// Basic Colourspaces\n// These colourspaces are generic names for any colourspace with the correct attributes.') for basic_role in [role for role in ofx_config.getRoles() if role[0] in basic_roles]: print_basic_colourspace(basic_role) diff --git a/scripts/genOCIOConfig b/scripts/genOCIOConfig index 012f32a4..84fa937e 100755 --- a/scripts/genOCIOConfig +++ b/scripts/genOCIOConfig @@ -5,7 +5,7 @@ # Create an OCIO config equivalant to OpenFX Native colour management # Example invocation: -# scripts/genOCIOConfig > include/openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3.ocio +# scripts/genOCIOConfig > include/openfx-native-1.5.ocio import PyOpenColorIO as OCIO @@ -15,19 +15,10 @@ ofx_config = OCIO.Config.CreateFromBuiltinConfig('studio-config-v2.1.0_aces-v1.3 srgb_tx = ofx_config.getColorSpace('srgb_tx') srgb_tx.setEncoding('sdr-video') -# Add OFX-specific roles for use as "basic colourspaces". -# Suitable colourspaces are defined for OCIO compatibility, but a plug-in/host operating -# in basic mode might not be using these exact colourspaces. -ofx_config.setRole('ofx_sdr', 'rec1886_rec709_display') -ofx_config.setRole('ofx_hdr', 'rec2100_hlg_display') -ofx_config.setRole('ofx_log', 'ACEScct') -ofx_config.setRole('ofx_linear', 'ACEScg') -ofx_config.setRole('ofx_raw', 'raw') - # Make all colourspaces active, future OCIO configs will also do this ofx_config.setInactiveColorSpaces('') -ofx_config.setName(f'openfx-{ofx_config.getName()}') +ofx_config.setName(f'openfx-native-v1.5_aces-v1.3_ocio-v2.3') ofx_config.setDescription(f'OpenFX 1.5 Native Mode Config\nBased on: {ofx_config.getDescription()}') ofx_config.validate() # will throw if there's an error