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
- Variables
- func Avatar2D(skin *image.NRGBA, size int) *image.NRGBA
- func Avatar3D(skin *image.NRGBA, size int) *image.NRGBA
- func CapePreview(cape image.Image, height int) *image.NRGBA
- func Encode(img image.Image, format string) ([]byte, error)
- func Format(webp bool, w, h int) string
- func Normalize(src image.Image) *image.NRGBA
- func Placeholder() *image.NRGBA
- func SkinPreview(skin *image.NRGBA, slim bool, height int) *image.NRGBA
- func Snap(n int, allowed []int, def int) int
- type AvatarRequest
- type PreviewRequest
- type Provider
- type Service
- func (s *Service) ActiveProvider() Provider
- func (s *Service) ClearProvider(owner string)
- func (s *Service) Get(ctx context.Context, key string, render func() ([]byte, error)) ([]byte, error)
- func (s *Service) GetWithCacheable(ctx context.Context, key string, render func() ([]byte, bool, error)) ([]byte, bool, error)
- func (s *Service) InvalidateCache()
- func (s *Service) ProviderCacheTag() string
- func (s *Service) ProviderOwner() string
- func (s *Service) RenderAvatarWithProvider(ctx context.Context, req AvatarRequest, builtin func() ([]byte, error)) ([]byte, error)
- func (s *Service) RenderAvatarWithProviderStatus(ctx context.Context, req AvatarRequest, builtin func() ([]byte, error)) (data []byte, cacheable bool, err error)
- func (s *Service) RenderPreviewWithProvider(ctx context.Context, req PreviewRequest, builtin func() ([]byte, error)) ([]byte, error)
- func (s *Service) RenderPreviewWithProviderStatus(ctx context.Context, req PreviewRequest, builtin func() ([]byte, error)) (data []byte, cacheable bool, err error)
- func (s *Service) SetProvider(owner string, p Provider)
Constants ¶
const ( PNG = "png" WebP = "webp" )
Formats an image can be encoded in.
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 ¶
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.
var PreviewHeights = []int{64, 100, 128, 150, 200, 256, 300, 400, 512}
PreviewHeights are the preview heights served.
Functions ¶
func Avatar3D ¶
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 ¶
CapePreview draws the outer face of a cape (the side seen from behind), height pixels tall.
func Normalize ¶
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 ¶
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 ¶
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.
Types ¶
type AvatarRequest ¶ added in v1.1.0
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 ¶
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
ActiveProvider returns the currently registered custom RenderProvider, or nil.
func (*Service) ClearProvider ¶ added in v1.1.0
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
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
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
SetProvider atomically activates a custom RenderProvider under owner and clears cached renders so subsequent requests pick up the new renderer immediately.