MVKPipeline: Support framebuffer logic operations.

This support was always there in Metal. It was just hidden from public
view--but not from prying eyes on the Objective-C metadata.

I had initially thought they were using OpenGL/Vulkan values for the
logic operation. When that didn't work, I then tried D3D11 values. I
guess D3D11 makes sense, because the Intel GPU drivers were the first to
support this in Metal.

Move the definition of `MVK_USE_METAL_PRIVATE_API` into
`"MVKCommonEnvironment.h"` so we can use it from non-C++ code.

Common/MVKCommonEnvironment.h

@@ -125,6 +125,19 @@ extern "C" {
 									 (__IPHONE_OS_VERSION_MAX_ALLOWED >= 140000))
 #endif
 
+/**
+ * Enable use of private Metal APIs.
+ *
+ * Enabling this build setting during a MoltenVK build will allow MoltenVK to
+ * extend its functionality by using certain private Metal API calls, but it 
+ * will also disqualify the app from being distributed via Apple App Stores.
+ *
+ * Disabled by default.
+ */
+#ifndef MVK_USE_METAL_PRIVATE_API
+#	define MVK_USE_METAL_PRIVATE_API		0
+#endif
+
 /** Directive to identify public symbols. */
 #define MVK_PUBLIC_SYMBOL    __attribute__((visibility("default"))) __attribute__((used))
 

Docs/Whats_New.md

@@ -20,6 +20,7 @@ Released TBD
 
 - Add `MVK_USE_METAL_PRIVATE_API` build setting to allow **MoltenVK** to be built with access to _Metal_ private API calls.
 - Add support for `VkPhysicalDeviceFeatures::wideLines` feature when `MVK_USE_METAL_PRIVATE_API` is enabled in a **MoltenVK** build.
+- Add support for the `VkPhysicalDeviceFeatures::logicOp` feature when `MVK_USE_METAL_PRIVATE_API` is enabled in a **MoltenVK** build.
 - Fix potential crash when using multi-planar images.
 - Ensure buffers available for buffer addresses in push constants.
 - Support `libMoltenVK.dylib` for _iOS Simulator_ architecture.

MoltenVK/MoltenVK.xcodeproj/project.pbxproj

@@ -140,6 +140,10 @@
 		45557A5321C9EFF3008868BD /* MVKCodec.mm in Sources */ = {isa = PBXBuildFile; fileRef = 45557A4D21C9EFF3008868BD /* MVKCodec.mm */; };
 		45557A5421C9EFF3008868BD /* MVKCodec.h in Headers */ = {isa = PBXBuildFile; fileRef = 45557A5121C9EFF3008868BD /* MVKCodec.h */; };
 		45557A5521C9EFF3008868BD /* MVKCodec.h in Headers */ = {isa = PBXBuildFile; fileRef = 45557A5121C9EFF3008868BD /* MVKCodec.h */; };
+		45E3A40B2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h in Headers */ = {isa = PBXBuildFile; fileRef = 45E3A4062166B922005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h */; };
+		45E3A40C2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h in Headers */ = {isa = PBXBuildFile; fileRef = 45E3A4062166B922005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h */; };
+		45E3A40D2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m in Sources */ = {isa = PBXBuildFile; fileRef = 45E3A40A2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m */; };
+		45E3A40E2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m in Sources */ = {isa = PBXBuildFile; fileRef = 45E3A40A2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m */; };
 		A9096E5E1F81E16300DFBEA6 /* MVKCmdDispatch.mm in Sources */ = {isa = PBXBuildFile; fileRef = A9096E5D1F81E16300DFBEA6 /* MVKCmdDispatch.mm */; };
 		A9096E5F1F81E16300DFBEA6 /* MVKCmdDispatch.mm in Sources */ = {isa = PBXBuildFile; fileRef = A9096E5D1F81E16300DFBEA6 /* MVKCmdDispatch.mm */; };
 		A909F65F213B190700FCD6BE /* MVKExtensions.h in Headers */ = {isa = PBXBuildFile; fileRef = A909F65A213B190600FCD6BE /* MVKExtensions.h */; };
@@ -582,6 +586,8 @@
 		45557A4D21C9EFF3008868BD /* MVKCodec.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = MVKCodec.mm; sourceTree = "<group>"; };
 		45557A5121C9EFF3008868BD /* MVKCodec.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MVKCodec.h; sourceTree = "<group>"; };
 		45557A5721CD83C3008868BD /* MVKDXTnCodec.def */ = {isa = PBXFileReference; explicitFileType = sourcecode.cpp.h; fileEncoding = 4; path = MVKDXTnCodec.def; sourceTree = "<group>"; };
+		45E3A4062166B922005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h"; sourceTree = "<group>"; };
+		45E3A40A2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m"; sourceTree = "<group>"; };
 		A9096E5C1F81E16300DFBEA6 /* MVKCmdDispatch.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MVKCmdDispatch.h; sourceTree = "<group>"; };
 		A9096E5D1F81E16300DFBEA6 /* MVKCmdDispatch.mm */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.objcpp; path = MVKCmdDispatch.mm; sourceTree = "<group>"; };
 		A909F65A213B190600FCD6BE /* MVKExtensions.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MVKExtensions.h; sourceTree = "<group>"; };
@@ -904,6 +910,8 @@
 				453638302508A4C6000EFFD3 /* MTLRenderPassStencilAttachmentDescriptor+MoltenVK.m */,
 				A9E53DFE21064F84002781DD /* MTLRenderPipelineDescriptor+MoltenVK.h */,
 				A9E53DFA21064F84002781DD /* MTLRenderPipelineDescriptor+MoltenVK.m */,
+				45E3A4062166B922005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h */,
+				45E3A40A2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m */,
 				A9E53DD32100B197002781DD /* MTLSamplerDescriptor+MoltenVK.h */,
 				A9E53DCD2100B197002781DD /* MTLSamplerDescriptor+MoltenVK.m */,
 				A9E53DD02100B197002781DD /* MTLTextureDescriptor+MoltenVK.h */,
@@ -1086,6 +1094,7 @@
 				A94FB7BC1C7DFB4800632CA3 /* MVKCmdPipeline.h in Headers */,
 				A9F3D9DC24732A4D00745190 /* MVKSmallVectorAllocator.h in Headers */,
 				A9C327562AAFBD390025EE79 /* MVKConfigMembers.def in Headers */,
+				45E3A40B2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h in Headers */,
 				A94FB7F81C7DFB4800632CA3 /* MVKPipeline.h in Headers */,
 				A94FB7F01C7DFB4800632CA3 /* MVKImage.h in Headers */,
 				4553AEFD2251617100E8EBCD /* MVKBlockObserver.h in Headers */,
@@ -1163,6 +1172,7 @@
 				A94FB7C51C7DFB4800632CA3 /* MVKCmdRendering.h in Headers */,
 				A94FB7BD1C7DFB4800632CA3 /* MVKCmdPipeline.h in Headers */,
 				A9F3D9DD24732A4D00745190 /* MVKSmallVectorAllocator.h in Headers */,
+				45E3A40C2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h in Headers */,
 				A94FB7F91C7DFB4800632CA3 /* MVKPipeline.h in Headers */,
 				A9C327582AAFBD3A0025EE79 /* MVKConfigMembers.def in Headers */,
 				A94FB7F11C7DFB4800632CA3 /* MVKImage.h in Headers */,
@@ -1776,6 +1786,7 @@
 				A9E53DE92100B197002781DD /* CAMetalLayer+MoltenVK.mm in Sources */,
 				A9096E5E1F81E16300DFBEA6 /* MVKCmdDispatch.mm in Sources */,
 				A99C90F0229455B300A061DA /* MVKCmdDebug.mm in Sources */,
+				45E3A40D2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -1836,6 +1847,7 @@
 				A9E53DEA2100B197002781DD /* CAMetalLayer+MoltenVK.mm in Sources */,
 				A9096E5F1F81E16300DFBEA6 /* MVKCmdDispatch.mm in Sources */,
 				A99C90F1229455B300A061DA /* MVKCmdDebug.mm in Sources */,
+				45E3A40E2166B923005E3E38 /* MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

MoltenVK/MoltenVK/API/mvk_datatypes.h

@@ -342,6 +342,9 @@ MTLBlendOperation mvkMTLBlendOperationFromVkBlendOp(VkBlendOp vkBlendOp);
 /** Returns the Metal MTLBlendFactor corresponding to the specified Vulkan VkBlendFactor. */
 MTLBlendFactor mvkMTLBlendFactorFromVkBlendFactor(VkBlendFactor vkBlendFactor);
 
+/** Returns the Metal MTLLogicOperation corresponding to the specified Vulkan VkLogicOp. */
+NSUInteger mvkMTLLogicOperationFromVkLogicOp(VkLogicOp vkBlendOp);
+
 /**
  * Returns the Metal MTLVertexFormat corresponding to the specified
  * Vulkan VkFormat as used as a vertex attribute format.

MoltenVK/MoltenVK/GPUObjects/MVKDevice.mm

@@ -2338,6 +2338,7 @@ void MVKPhysicalDevice::initFeatures() {
     _features.fullDrawIndexUint32 = true;
     _features.independentBlend = true;
     _features.sampleRateShading = true;
+	_features.logicOp = getMVKConfig().useMetalPrivateAPI;
     _features.depthBiasClamp = true;
     _features.fillModeNonSolid = true;
     _features.largePoints = true;

MoltenVK/MoltenVK/GPUObjects/MVKPipeline.mm

@@ -23,6 +23,9 @@
 #include "MVKOSExtensions.h"
 #include "MVKStrings.h"
 #include "MTLRenderPipelineDescriptor+MoltenVK.h"
+#if MVK_USE_METAL_PRIVATE_API
+#include "MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h"
+#endif
 #include "mvk_datatypes.hpp"
 
 #ifndef MVK_USE_CEREAL
@@ -1616,6 +1619,12 @@ void MVKGraphicsPipeline::addFragmentOutputToPipeline(MTLRenderPipelineDescripto
                 colorDesc.alphaBlendOperation = mvkMTLBlendOperationFromVkBlendOp(pCA->alphaBlendOp);
                 colorDesc.sourceAlphaBlendFactor = mvkMTLBlendFactorFromVkBlendFactor(pCA->srcAlphaBlendFactor);
                 colorDesc.destinationAlphaBlendFactor = mvkMTLBlendFactorFromVkBlendFactor(pCA->dstAlphaBlendFactor);
+#if MVK_USE_METAL_PRIVATE_API
+				if (getMVKConfig().useMetalPrivateAPI) {
+					colorDesc.logicOpEnabledMVK = pCreateInfo->pColorBlendState->logicOpEnable;
+					colorDesc.logicOpMVK = mvkMTLLogicOperationFromVkLogicOp(pCreateInfo->pColorBlendState->logicOp);
+				}
+#endif
             }
         }
     }

MoltenVK/MoltenVK/OS/MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h

@@ -0,0 +1,46 @@
+/*
+ * MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.h
+ *
+ * Copyright (c) 2018-2023 Chip Davis
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#import <Metal/Metal.h>
+
+
+/** Extensions to MTLRenderPipelineColorAttachmentDescriptor to support MoltenVK. */
+@interface MTLRenderPipelineColorAttachmentDescriptor (MoltenVK)
+
+/**
+ * Replacement for the logicOpEnabled property.
+ *
+ * This property allows support under all OS versions. Delegates to the logicOpEnabled
+ * property if it is available. otherwise, returns NO when read and does nothing when set.
+ */
+@property(nonatomic, readwrite, getter=isLogicOpEnabledMVK) BOOL logicOpEnabledMVK;
+
+/**
+ * Replacement for the logicOp property.
+ *
+ * This property allows support under all OS versions. Delegates to the logicOp
+ * property if it is available. otherwise, returns MTLLogicOperationCopy when
+ * read and does nothing when set.
+ *
+ * The value is treated as an NSUInteger to support OS versions on which the enum is unavailable.
+ */
+@property(nonatomic, readwrite) NSUInteger logicOpMVK;
+
+@end

MoltenVK/MoltenVK/OS/MTLRenderPipelineColorAttachmentDescriptor+MoltenVK.m

@@ -0,0 +1,67 @@
+/*
+ * MTLRenderPipelineDescriptor+MoltenVK.m
+ *
+ * Copyright (c) 2018-2023 Chip Davis
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+#include "MVKCommonEnvironment.h"
+
+#if MVK_USE_METAL_PRIVATE_API
+
+#include "MTLRenderPipelineDescriptor+MoltenVK.h"
+
+typedef NSUInteger MTLLogicOperation;
+
+@interface MTLRenderPipelineColorAttachmentDescriptor ()
+
+- (BOOL)isLogicOpEnabled;
+- (void)setLogicOpEnabled: (BOOL)enable;
+- (MTLLogicOperation)logicOp;
+- (void)setLogicOp: (MTLLogicOperation)op;
+
+@end
+
+@implementation MTLRenderPipelineColorAttachmentDescriptor (MoltenVK)
+
+- (BOOL)isLogicOpEnabledMVK {
+	if ([self respondsToSelector:@selector(isLogicOpEnabled)]) {
+		return [self isLogicOpEnabled];
+	}
+	return NO;
+}
+
+- (void)setLogicOpEnabledMVK: (BOOL)enable {
+	if ([self respondsToSelector:@selector(setLogicOpEnabled:)]) {
+		[self setLogicOpEnabled: enable];
+	}
+}
+
+- (NSUInteger)logicOpMVK {
+	if ([self respondsToSelector:@selector(logicOp)]) {
+		return [self logicOp];
+	}
+	return 3 /* MTLLogicOperationCopy */;
+}
+
+- (void)setLogicOpMVK: (MTLLogicOperation)op {
+	if ([self respondsToSelector:@selector(setLogicOp:)]) {
+		[self setLogicOp: (MTLLogicOperation)op];
+	}
+}
+
+@end
+
+#endif	/* MVK_CONFIG_SUPPORT_METAL_SPIS */

MoltenVK/MoltenVK/Utility/MVKEnvironment.h

@@ -23,7 +23,9 @@
 #include "mvk_vulkan.h"
 #include "mvk_private_api.h"
 #include "MVKLogging.h"
+#ifdef __cplusplus
 #include <string>
+#endif
 
 
 // Expose MoltenVK Apple surface extension functionality
@@ -73,23 +75,12 @@
 #	define MVK_SUPPORT_IOSURFACE_BOOL (__TV_OS_VERSION_MIN_REQUIRED >= __TVOS_11_0)
 #endif
 
-/**
- * Enable use of private Metal APIs.
- *
- * Enabling this build setting during a MoltenVK build will allow MoltenVK to
- * extend its functionality by using certain private Metal API calls, but it 
- * will also disqualify the app from being distributed via Apple App Stores.
- *
- * Disabled by default.
- */
-#ifndef MVK_USE_METAL_PRIVATE_API
-#	define MVK_USE_METAL_PRIVATE_API		0
-#endif
-
 
 #pragma mark -
 #pragma mark MoltenVK Configuration
 
+#ifdef __cplusplus
+
 /** The number of members of MVKConfiguration that are strings. */
 static constexpr uint32_t kMVKConfigurationStringCount = 1;
 
@@ -105,6 +96,8 @@ void mvkSetGlobalConfig(const MVKConfiguration& srcMVKConfig);
  */
 void mvkSetConfig(MVKConfiguration& dstMVKConfig, const MVKConfiguration& srcMVKConfig, std::string* stringHolders);
 
+#endif
+
 /**
  * Enable debug mode.
  * By default, disabled for Release builds and enabled for Debug builds.

MoltenVK/MoltenVK/Vulkan/mvk_datatypes.mm

@@ -433,6 +433,52 @@ MVK_PUBLIC_SYMBOL MTLBlendFactor mvkMTLBlendFactorFromVkBlendFactor(VkBlendFacto
 	}
 }
 
+#if MVK_USE_METAL_PRIVATE_API
+
+// This isn't in any public header yet. I'm really just guessing based on the D3D11 values here.
+typedef NS_ENUM(NSUInteger, MTLLogicOperation) {
+	MTLLogicOperationClear,
+	MTLLogicOperationSet,
+	MTLLogicOperationCopy,
+	MTLLogicOperationCopyInverted,
+	MTLLogicOperationNoop,
+	MTLLogicOperationInvert,
+	MTLLogicOperationAnd,
+	MTLLogicOperationNand,
+	MTLLogicOperationOr,
+	MTLLogicOperationNor,
+	MTLLogicOperationXor,
+	MTLLogicOperationEquivalence,
+	MTLLogicOperationAndReverse,
+	MTLLogicOperationAndInverted,
+	MTLLogicOperationOrReverse,
+	MTLLogicOperationOrInverted,
+};
+
+MVK_PUBLIC_SYMBOL NSUInteger mvkMTLLogicOperationFromVkLogicOp(VkLogicOp vkLogicOp) {
+	switch (vkLogicOp) {
+		case VK_LOGIC_OP_CLEAR:			return MTLLogicOperationClear;
+		case VK_LOGIC_OP_AND:			return MTLLogicOperationAnd;
+		case VK_LOGIC_OP_AND_REVERSE:	return MTLLogicOperationAndReverse;
+		case VK_LOGIC_OP_COPY:			return MTLLogicOperationCopy;
+		case VK_LOGIC_OP_AND_INVERTED:	return MTLLogicOperationAndInverted;
+		case VK_LOGIC_OP_NO_OP:			return MTLLogicOperationNoop;
+		case VK_LOGIC_OP_XOR:			return MTLLogicOperationXor;
+		case VK_LOGIC_OP_OR:			return MTLLogicOperationOr;
+		case VK_LOGIC_OP_NOR:			return MTLLogicOperationNor;
+		case VK_LOGIC_OP_EQUIVALENT:	return MTLLogicOperationEquivalence;
+		case VK_LOGIC_OP_INVERT:		return MTLLogicOperationInvert;
+		case VK_LOGIC_OP_OR_REVERSE:	return MTLLogicOperationOrReverse;
+		case VK_LOGIC_OP_COPY_INVERTED:	return MTLLogicOperationCopyInverted;
+		case VK_LOGIC_OP_OR_INVERTED:	return MTLLogicOperationOrInverted;
+		case VK_LOGIC_OP_NAND:			return MTLLogicOperationNand;
+		case VK_LOGIC_OP_SET:			return MTLLogicOperationSet;
+		default:						return MTLLogicOperationCopy;
+	}
+}
+
+#endif
+
 MVK_PUBLIC_SYMBOL MTLVertexStepFunction mvkMTLVertexStepFunctionFromVkVertexInputRate(VkVertexInputRate vkVtxStep) {
 	switch (vkVtxStep) {
 		case VK_VERTEX_INPUT_RATE_VERTEX:		return MTLVertexStepFunctionPerVertex;

README.md

@@ -328,6 +328,7 @@ included in any of the `make` command-line build commands [mentioned above](#com
 
 Functionality added with `MVK_USE_METAL_PRIVATE_API` enabled includes:
 - `VkPhysicalDeviceFeatures::wideLines`
+- `VkPhysicalDeviceFeatures::logicOp`
 
 
 <a name="demos"></a>