# HardwareVariant Enum in OCLP-Mod: Categorizing and Applying Hardware-Specific Patches

> Discover the HardwareVariant enum in OCLP-Mod. Learn how it categorizes patches for Graphics Networking Audio and Miscellaneous for efficient hardware-specific patch application and organization.

- Repository: [laobamac/oclp-mod](https://github.com/laobamac/oclp-mod)
- Tags: internals
- Published: 2026-03-05

---

**The `HardwareVariant` enum in laobamac/oclp-mod serves as the central taxonomy that classifies every hardware-specific patch into Graphics, Networking, Audio, or Miscellaneous categories, enabling the detection engine to aggregate patches and the GUI to present them in organized sections.**

The `HardwareVariant` enum is the foundational classification system within the OCLP-Mod project (OpenCore Legacy Patcher Mod), a fork designed to extend macOS compatibility to unsupported hardware. Located in [`oclp_mod/sys_patch/patchsets/hardware/base.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/base.py), this string-based enumeration ensures that every hardware patch—whether for legacy GPUs, unsupported Wi-Fi cards, or audio controllers—is categorized correctly for detection, aggregation, and user interface presentation.

## What Is the HardwareVariant Enum?

`HardwareVariant` is implemented as a `StrEnum` (string enumeration) that defines four top-level hardware categories. Each variant maps to a Chinese label used in the GUI, reflecting the project's internationalization approach. The enum declaration in [`oclp_mod/sys_patch/patchsets/hardware/base.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/base.py) is:

```python
class HardwareVariant(StrEnum):
    """
    Hardware variant for patch set
    """
    GRAPHICS:      str = "显卡"
    NETWORKING:    str = "网卡"
    AUDIO:         str = "音频"
    MISCELLANEOUS: str = "杂项"

```

Every concrete hardware patch class inherits from the abstract `BaseHardware` class and must implement the `hardware_variant()` method, returning the appropriate `HardwareVariant` member. This contract ensures the detection engine can query any patch instance and immediately know its categorical classification.

## How HardwareVariant Drives Patch Classification

The enum serves four critical architectural purposes that bridge low-level hardware detection with high-level user interaction.

**Classification and Inheritance**

Each hardware patch explicitly declares its category. For example, `ModernWireless` (handling Broadcom Wi-Fi cards) returns `HardwareVariant.NETWORKING`, while `NvidiaWebDriver` returns `HardwareVariant.GRAPHICS`. This declaration resides in the individual patch file within `oclp_mod/sys_patch/patchsets/hardware/` subdirectories.

**Detection and Aggregation**

The `HardwarePatchsetDetection` class in [`oclp_mod/sys_patch/patchsets/detect.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/detect.py) orchestrates system scanning. It iterates over all registered hardware patch classes, instantiates them with system parameters (XNU kernel version, OS build), and checks `present()` and `native_os()` methods. Crucially, it groups results using the `HardwareVariant` as a dictionary key:

```python
for hw_cls in self._hardware_variants:
    hw = hw_cls(xnu_major, xnu_minor, os_build, self._constants)
    if hw.present() and hw.native_os():
        category = hw.hardware_variant()
        self.device_properties.setdefault(category, []).append(hw)

```

This aggregation produces `device_properties`, a structured dictionary where each key is a `HardwareVariant` (e.g., `"显卡"`, `"网卡"`) and each value is a list of applicable patch objects for that category.

## Graphics Subclassification with HardwareVariantGraphicsSubclass

Graphics patches require finer granularity than the four main categories provide. To address this, OCLP-Mod implements a secondary enum, `HardwareVariantGraphicsSubclass`, also defined in [`oclp_mod/sys_patch/patchsets/hardware/base.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/base.py).

This subclass enum distinguishes between **Non-Metal Graphics**, **Metal 3802** (for specific AMD GPUs), and other graphics implementations. Patch classes like `NvidiaWebDriver` or `LegacyAMD` override the `hardware_variant_graphics_subclass()` method to return the appropriate subclass value, while still maintaining `HardwareVariant.GRAPHICS` as their primary category.

This dual-layer taxonomy allows the detection engine to apply graphics-specific logic (such as selecting between Metal and Non-Metal kernel patches) while maintaining consistent top-level categorization for UI presentation.

## Practical Usage in GUI and Patch Application

The GUI modules leverage `HardwareVariant` to create organized, user-friendly patch displays. Files such as [`oclp_mod/wx_gui/gui_sys_patch_display.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/wx_gui/gui_sys_patch_display.py) and [`gui_sys_patch_start.py`](https://github.com/laobamac/oclp-mod/blob/main/gui_sys_patch_start.py) import the enum and use it to label tree view sections or panel headers.

When rendering available patches, the GUI iterates over the aggregated `device_properties` dictionary:

```python

# Simplified example from gui_sys_patch_display.py

for variant in HardwareVariant:
    patch_set = patches.get(variant)
    if not patch_set:
        continue
    variant_item = self.tree.AppendItem(root, variant.value)  # Displays "显卡", "网卡", etc.

    for patch in patch_set:
        self.tree.AppendItem(variant_item, patch.name())

```

This implementation ensures that users see logically grouped options—such as all networking patches under "网卡" (Networking)—rather than an unstructured list of technical patch names.

## Creating Custom Hardware Patches with HardwareVariant

Developers extending OCLP-Mod can implement new hardware support by inheriting from `BaseHardware` and specifying the appropriate `HardwareVariant`. The contract requires implementing four key methods: `name()`, `present()`, `native_os()`, and `hardware_variant()`.

Here is a complete example for a hypothetical custom audio patch:

```python
from oclp_mod.sys_patch.patchsets.hardware.base import BaseHardware, HardwareVariant

class MyCustomAudioController(BaseHardware):
    def name(self) -> str:
        """Return human-readable patch name"""
        return "Custom Audio Controller Patch"

    def present(self) -> bool:
        """Detection logic: check if hardware is present"""
        return any(
            dev.device_id == 0x1234 
            for dev in self._computer.audio_devices
        )

    def native_os(self) -> bool:
        """Determine if patch applies to current OS version"""
        return self._xnu_major >= 22  # macOS Ventura+

    def hardware_variant(self) -> HardwareVariant:
        """Return the categorical classification"""
        return HardwareVariant.AUDIO

```

When this class is registered with the patch detection system, it automatically appears under the "音频" (Audio) section in the GUI, grouped with other audio-related patches.

## Summary

- **HardwareVariant** is a `StrEnum` defined in [`oclp_mod/sys_patch/patchsets/hardware/base.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/base.py) that categorizes patches into **Graphics** ("显卡"), **Networking** ("网卡"), **Audio** ("音频"), and **Miscellaneous** ("杂项").
- The enum enables **HardwarePatchsetDetection** ([`detect.py`](https://github.com/laobamac/oclp-mod/blob/main/detect.py)) to aggregate applicable patches by category into the `device_properties` dictionary.
- Concrete patch classes inherit from `BaseHardware` and implement `hardware_variant()` to declare their category, establishing a strict classification contract.
- **HardwareVariantGraphicsSubclass** provides secondary granularity for graphics patches, distinguishing between Non-Metal and Metal implementations while maintaining the primary Graphics category.
- GUI modules use the enum values to organize patch displays into logical sections, presenting Chinese labels ("显卡", "网卡", etc.) to users for clarity.

## Frequently Asked Questions

### How does HardwareVariant differ from HardwareVariantGraphicsSubclass?

**HardwareVariant** provides the top-level categorical taxonomy used across all patch types, while **HardwareVariantGraphicsSubclass** offers granular classification exclusively for graphics patches. When a patch returns `HardwareVariant.GRAPHICS`, it may additionally specify a subclass such as `NON_METAL_GRAPHICS` or `METAL_3802` to trigger specific kernel patching logic, while the GUI still groups it under the main "显卡" (Graphics) category.

### Where is the HardwareVariant enum defined and what are its values?

The enum is defined in **[`oclp_mod/sys_patch/patchsets/hardware/base.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/base.py)** as a `StrEnum` with four members: `GRAPHICS` (value: "显卡"), `NETWORKING` (value: "网卡"), `AUDIO` (value: "音频"), and `MISCELLANEOUS` (value: "杂项"). These Chinese string values are used directly in the GUI to label patch categories.

### How does the detection engine use HardwareVariant to organize patches?

The **`HardwarePatchsetDetection`** class in [`oclp_mod/sys_patch/patchsets/detect.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/detect.py) iterates through all hardware patch classes, instantiates them, and checks their applicability. For each patch that passes detection, it calls `hardware_variant()` to obtain the category enum, then aggregates the patch into a dictionary (`device_properties`) keyed by that enum. This creates a structured data structure where all networking patches reside under `HardwareVariant.NETWORKING`, all graphics under `HardwareVariant.GRAPHICS`, and so on.

### Can developers extend HardwareVariant with new categories?

While the enum definition in [`base.py`](https://github.com/laobamac/oclp-mod/blob/main/base.py) contains the four canonical categories, the architecture supports extension through the **`MISCELLANEOUS`** category for hardware that does not fit Graphics, Networking, or Audio classifications. Developers implementing new patch classes should return `HardwareVariant.MISCELLANEOUS` for specialized hardware (such as legacy USB controllers or storage controllers) unless the core enum is modified to include a new top-level category. The `StrEnum` type ensures that any future additions will integrate seamlessly with the existing string-based GUI labels.