render

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package render draws avatars (a skin's head, flat or as a cube) and previews (the skin seen from the front and the back, or a cape) for /avatar and /preview. All drawing is nearest-neighbour: skins are pixel art, and Blessing Skin's smoothed resize blurred them.

Index

Constants

View Source
const (
	PNG  = "png"
	WebP = "webp"
)

Formats an image can be encoded in.

View Source
const WebPMaxPixels = 300 * 300

WebPMaxPixels is the largest picture served as WebP: the pure-Go encoder takes about 15 ms for 256×256 but 55 ms for 512×512, against PNG's 6 to 15 ms, and a render that misses the cache should take under 50 ms (design 04 §5.4). Larger pictures, rarely asked for, are PNG (about twice the bytes).

Variables

View Source
var AvatarSizes = []int{16, 24, 32, 48, 64, 96, 100, 128, 256, 512}

AvatarSizes are the avatar sizes served (docs/design/02 §2.5); others snap to the nearest, so each texture has a bounded number of renders to cache.

View Source
var PreviewHeights = []int{64, 100, 128, 150, 200, 256, 300, 400, 512}

PreviewHeights are the preview heights served.

Functions

func Avatar2D

func Avatar2D(skin *image.NRGBA, size int) *image.NRGBA

Avatar2D draws the face (with the hat layer) as a size×size square.

func Avatar3D

func Avatar3D(skin *image.NRGBA, size int) *image.NRGBA

Avatar3D draws the head as a cube seen from above, in front and to its left: the top, the face and the left side, each with its hat layer, shaded so the edges read.

func CapePreview

func CapePreview(cape image.Image, height int) *image.NRGBA

CapePreview draws the outer face of a cape (the side seen from behind), height pixels tall.

func Encode

func Encode(img image.Image, format string) ([]byte, error)

Encode encodes img as PNG or (lossless) WebP.

func Format

func Format(webp bool, w, h int) string

Format is the format to encode a w×h picture in when the client takes WebP.

func Normalize

func Normalize(src image.Image) *image.NRGBA

Normalize returns a skin in the square 64×64 layout (at its own resolution). As in Minecraft, a legacy 64×32 skin gets left limbs mirrored from the right ones and an overlay area that is entirely opaque counts as empty (old skins filled it with a colour); the base layer is drawn opaque, the overlay with its transparency.

func Placeholder

func Placeholder() *image.NRGBA

Placeholder is a plain grey skin, drawn when there is no skin to draw: no texture, a missing file, or a skin the viewer may not see.

func SkinPreview

func SkinPreview(skin *image.NRGBA, slim bool, height int) *image.NRGBA

SkinPreview draws the skin from an angled front view and an angled back view side by side (matching Blessing Skin's 3D oblique angle with nearest-neighbour pixel art), height pixels tall, within a 9:8 canvas.

func Snap

func Snap(n int, allowed []int, def int) int

Snap returns the allowed value nearest to n (the larger one on a tie), or def for n <= 0.

Types

type AvatarRequest added in v1.1.0

type AvatarRequest struct {
	SkinPNG []byte
	Size    int
	Is3D    bool
	Format  string // "png" | "webp"
}

AvatarRequest describes an avatar render delegated to a custom RenderProvider.

type PreviewRequest added in v1.1.0

type PreviewRequest struct {
	TexturePNG  []byte
	TextureType string // "steve" | "alex" | "cape"
	Height      int
	Format      string // "png" | "webp"
}

PreviewRequest describes a skin or cape preview render delegated to a custom RenderProvider.

type Provider added in v1.1.0

type Provider interface {
	RenderAvatar(ctx context.Context, req AvatarRequest) ([]byte, error)
	RenderPreview(ctx context.Context, req PreviewRequest) ([]byte, error)
}

Provider is a hot-swappable 2D/3D avatar and texture preview renderer registered by an authorized native plugin with the "provider.render" permission.

type Service

type Service struct {
	// contains filtered or unexported fields
}

func NewService

func NewService(workers, cacheBytes int) *Service

NewService creates a service with workers concurrent renders and a cache of at most cacheBytes encoded bytes.

func (*Service) ActiveProvider added in v1.1.0

func (s *Service) ActiveProvider() Provider

ActiveProvider returns the currently registered custom RenderProvider, or nil.

func (*Service) ClearProvider added in v1.1.0

func (s *Service) ClearProvider(owner string)

ClearProvider reverts to the built-in renderer if and only if owner currently holds the active RenderProvider slot.

func (*Service) Get

func (s *Service) Get(ctx context.Context, key string, render func() ([]byte, error)) ([]byte, error)

Get returns the result for key, calling render on a miss.

func (*Service) GetWithCacheable added in v1.1.0

func (s *Service) GetWithCacheable(ctx context.Context, key string, render func() ([]byte, bool, error)) ([]byte, bool, error)

GetWithCacheable returns the result for key, calling render on a miss and only storing the result in the LRU cache when cacheable is true and the cache generation did not rotate while render was in flight.

func (*Service) InvalidateCache added in v1.1.0

func (s *Service) InvalidateCache()

InvalidateCache clears all cached render outputs and bumps the cache generation.

func (*Service) ProviderCacheTag added in v1.1.0

func (s *Service) ProviderCacheTag() string

ProviderCacheTag returns "<owner>:g<generation>" when a custom RenderProvider is active (or "" for built-in), ensuring cache keys and ETags rotate on every provider hot-swap, reload, or explicit cache invalidation.

func (*Service) ProviderOwner added in v1.1.0

func (s *Service) ProviderOwner() string

ProviderOwner returns the active custom RenderProvider owner, or "" for built-in.

func (*Service) RenderAvatarWithProvider added in v1.1.0

func (s *Service) RenderAvatarWithProvider(
	ctx context.Context,
	req AvatarRequest,
	builtin func() ([]byte, error),
) ([]byte, error)

RenderAvatarWithProvider delegates to the active RenderProvider if present, falling back to builtin if no provider is active or the provider returns an error.

func (*Service) RenderAvatarWithProviderStatus added in v1.1.0

func (s *Service) RenderAvatarWithProviderStatus(
	ctx context.Context,
	req AvatarRequest,
	builtin func() ([]byte, error),
) (data []byte, cacheable bool, err error)

RenderAvatarWithProviderStatus behaves like RenderAvatarWithProvider and also reports whether the returned bytes are cacheable under the active provider key (false when a custom provider was active but failed and fell back to builtin).

func (*Service) RenderPreviewWithProvider added in v1.1.0

func (s *Service) RenderPreviewWithProvider(
	ctx context.Context,
	req PreviewRequest,
	builtin func() ([]byte, error),
) ([]byte, error)

RenderPreviewWithProvider delegates to the active RenderProvider if present, falling back to builtin if no provider is active or the provider returns an error.

func (*Service) RenderPreviewWithProviderStatus added in v1.1.0

func (s *Service) RenderPreviewWithProviderStatus(
	ctx context.Context,
	req PreviewRequest,
	builtin func() ([]byte, error),
) (data []byte, cacheable bool, err error)

RenderPreviewWithProviderStatus behaves like RenderPreviewWithProvider and also reports whether the returned bytes are cacheable under the active provider key.

func (*Service) SetProvider added in v1.1.0

func (s *Service) SetProvider(owner string, p Provider)

SetProvider atomically activates a custom RenderProvider under owner and clears cached renders so subsequent requests pick up the new renderer immediately.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL