shaders ¶

@classmethod
def ensure_obj(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> Self:
    """
    Ensure that the input is a scaler instance, resolving it if necessary.

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Scaler instance.
    """
    return _base_ensure_obj(cls, scaler, func_except)

@classmethod
def from_param(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> type[Self]:
    """
    Resolve and return a scaler type from a given input (string, type, or instance).

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Resolved scaler type.
    """
    return _base_from_param(cls, scaler, cls._err_class, func_except)

def get_scale_args(
    self,
    clip: vs.VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any,
) -> dict[str, Any]:
    """
    Generate the keyword arguments used for scaling.

    :param clip:    The source clip.
    :param shift:   Subpixel shift (top, left).
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Extra parameters to merge.
    :return:        Final dictionary of keyword arguments for the scale function.
    """
    return dict(width=width, height=height, src_top=shift[0], src_left=shift[1]) | self.kwargs | kwargs

@cached_property
def kernel_radius(self) -> int:
    """
    Return the effective kernel radius for the scaler.

    :raises CustomNotImplementedError:  If no kernel radius is defined.
    :return:                            Kernel radius.
    """
    ...

@deprecated('The "multi" method is deprecated. Use "supersample" instead.', category=DeprecationWarning)
def multi(
    self, clip: VideoNodeT, multi: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Deprecated alias for `supersample`.

    :param clip:    The source clip.
    :param multi:   Supersampling factor.
    :param shift:   Subpixel shift (top, left) applied during scaling.
    :param kwargs:  Additional arguments forwarded to the scale function.
    :return:        The supersampled clip.
    """
    return self.supersample(clip, multi, shift, **kwargs)

@cached_property
def pretty_string(self) -> str:
    """
    Cached property returning a user-friendly string representation.

    :return: Pretty-printed string with arguments.
    """
    return self._pretty_string()

def scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[float, float] = (0, 0),
    **kwargs: Any
) -> ConstantFormatVideoNode:
    assert check_variable(clip, self.__class__)

    width, height = self._wh_norm(clip, width, height)

    kwargs = self.kwargs | kwargs

    output = depth(clip, 16)

    # Add fake chroma planes
    if output.format.num_planes == 1:
        if width > output.width or height > output.height:
            output = output.resize.Point(format=vs.YUV444P16)
        else:
            for div in (4, 2):
                if width % div == 0 and height % div == 0:
                    blank = core.std.BlankClip(output, output.width // div, output.height // div, vs.GRAY16)
                    break
            else:
                blank = core.std.BlankClip(output, format=vs.GRAY16)

            output = join(output, blank, blank)

    # Configure filter param mainly used for chroma planes if input clip is GRAY. Box was slightly faster.
    if 'filter' not in kwargs:
        kwargs['filter'] = 'box' if output.format.num_planes == 1 else 'ewa_lanczos'

    output = core.placebo.Shader(
        output,
        self.shader,
        output.width * ceil(width / output.width),
        output.height * ceil(height / output.height),
        **kwargs
    )

    return self._finish_scale(output, clip, width, height, shift)

def supersample(
    self, clip: VideoNodeT, rfactor: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Supersample a clip by a given scaling factor.

    :param clip:                The source clip.
    :param rfactor:             Scaling factor for supersampling.
    :param shift:               Subpixel shift (top, left) applied during scaling.
    :param kwargs:              Additional arguments forwarded to the scale function.
    :raises CustomValueError:   If resulting resolution is non-positive.
    :return:                    The supersampled clip.
    """
    assert check_variable_resolution(clip, self.supersample)

    dst_width, dst_height = ceil(clip.width * rfactor), ceil(clip.height * rfactor)

    if max(dst_width, dst_height) <= 0.0:
        raise CustomValueError(
            'Multiplying the resolution by "rfactor" must result in a positive resolution!',
            self.supersample,
            rfactor,
        )

    return self.scale(clip, dst_width, dst_height, shift, **kwargs)  # type: ignore[return-value]