Fork me on GitHub

Custom grob functions

Intro

Although using piecepackr's configuration lists provide a powerful high-level way to alter the appearance of your piecepack graphics piecepackr also allows one to modify the appearance of your piecepack graphics even more with the use of custom grob functions.

Examples

Checkered Tile Backs

The default grob function doesn't support adding checkers to the back of your piecepack tiles but piecepackr does include a utility function checkersGrob that can be used via a custom grob function:

Warning

Some people (including the inventor James "Kyle" Droscha) feel that adding checkers to the back of one's piecepack is a bad idea, in particular they leak information about the direction of the tile face.

library("grid")
library("piecepackr")

checkeredPieceGrob <- function(piece_side, suit, rank, cfg) {
    cfg <- as_pp_cfg(cfg)
    opt <- cfg$get_piece_opt(piece_side, suit, rank)
    shape_fn <- get_shape_grob_fn(opt$shape, opt$shape_t, opt$shape_r)
    background_grob <- shape_fn(gp=gpar(col=NA, fill=opt$background_color))
    checkers_grob <- checkersGrob(opt$gridline_color, opt$shape, opt$shape_t)
    border_grob <- shape_fn(gp=gpar(col=opt$border_color, fill=NA))
    gl <- gList(background_grob, checkers_grob, border_grob)
    gTree(children=gl, name=piece_side)
}
cfg <- list(grob_fn.tile_back=checkeredPieceGrob)
grid.piece("preview_layout", cfg=cfg)
Custom grob function to use checkers on the tile back

Custom grob function to use checkers on the tile back

The above custom grob function was written fairly generally so it can also support convex# polygons (i.e. "Hexpack" tiles):

cfg <- list(grob_fn.tile_back=checkeredPieceGrob, shape.tile="convex6", shape.coin="convex3", shape.saucer="convex3")
grid.piece("preview_layout", cfg=cfg)
'checkersGrob' even works on hexagon shaped tiles

'checkersGrob' even works on hexagon shaped tiles

Pawn Belts with Three Suit Symbols

The pawn belts in Jonathan Dietrich's JCD piecepack and Chris Sakkas' Nine-Suit Piecepack both feature three suit symbols but it is difficult to replicate such a belt with piecepackr's default draw function since it only supports one primary symbol and one directional mark [*].

pawnBeltGrob <- function(piece_side, suit, rank, cfg) {
    cfg <- as_pp_cfg(cfg)
    opt <- cfg$get_piece_opt(piece_side, suit, rank)
    shape_fn <- get_shape_grob_fn(opt$shape, opt$shape_t, opt$shape_r)
    background_grob <- shape_fn(gp=gpar(col=NA, fill=opt$background_color))
    center_grob <- rectGrob(width=0.3, gp=gpar(col=NA, fill=opt$ps_color))
    gp_ps1 <- gpar(col=opt$background_color, fontsize=opt$ps_fontsize,
                  fontfamily=opt$ps_fontfamily, fontface=opt$ps_fontface)
    ps_grob1 <- textGrob(opt$ps_text, x=opt$ps_x, y=opt$ps_y, gp=gp_ps1)
    gp_ps2 <- gpar(col=opt$ps_color, fontsize=opt$ps_fontsize,
                  fontfamily=opt$ps_fontfamily, fontface=opt$ps_fontface)
    ps_grob2 <- textGrob(opt$ps_text, x=c(0.2, 0.8), gp=gp_ps2)
    border_grob <- shape_fn(gp=gpar(col=opt$border_color, fill=NA))
    gl <- gList(background_grob, center_grob, ps_grob1, ps_grob2, border_grob)

    gTree(children=gl, name=piece_side)
}
cfg <- list(grob_fn.belt=pawnBeltGrob)
grid.piece("belt_face", s=3, cfg=cfg)
Pawn belts with three suit symbols

Pawn belts with three suit symbols

[*]Technically if awkwardly you could replicate it by customizing the mat on the belt and putting two suit symbols separated by a bunch of whitespace as the directional mark symbols but the amount of whitespace needed would vary with the font and the fontsize so not a general solution and would require trial and error.

Low-level utilities

piecepackr comes with several utility functions that can aid in the writing of custom grob functions. For more documentation you can use the help function:

help("grob_fn_helpers")
help("pp_utils")

For help in writing your own custom grob functions it can also be instructive to look at the code of the default grob function basicPieceGrob:

print(basicPieceGrob)
## function (piece_side, suit, rank, cfg = pp_cfg())
## {
##     cfg <- as_pp_cfg(cfg)
##     opt <- cfg$get_piece_opt(piece_side, suit, rank)
##     shape_fn <- get_shape_grob_fn(opt$shape, opt$shape_t, opt$shape_r)
##     background_grob <- shape_fn(gp = gpar(col = NA, fill = opt$background_color))
##     gl_grob <- gridlinesGrob(opt$gridline_color, opt$shape, opt$shape_t,
##         opt$gridline_lex)
##     mat_grob <- matGrob(opt$mat_color, opt$shape, opt$shape_t,
##         opt$mat_width)
##     gp_ps <- gpar(col = opt$ps_color, fontsize = opt$ps_fontsize,
##         fontfamily = opt$ps_fontfamily, fontface = opt$ps_fontface)
##     ps_grob <- textGrob(opt$ps_text, x = opt$ps_x, y = opt$ps_y,
##         gp = gp_ps)
##     gp_dm <- gpar(col = opt$dm_color, fontsize = opt$dm_fontsize,
##         fontfamily = opt$dm_fontfamily, fontface = opt$ps_fontface)
##     dm_grob <- textGrob(opt$dm_text, x = opt$dm_x, y = opt$dm_y,
##         gp = gp_dm)
##     border_grob <- shape_fn(gp = gpar(col = opt$border_color,
##         fill = NA, lex = opt$border_lex))
##     gl <- gList(background_grob, gl_grob, mat_grob, ps_grob,
##         dm_grob, border_grob)
##     gTree(children = gl, name = piece_side)
## }
## <bytecode: 0x55d8cb3437f8>
## <environment: namespace:piecepackr>

In order to draw custom grob functions it may also be helpful to learn more about grid's API. Some may also find the grImport2 package useful.

Comments


There are no comments yet.

Add a Comment

You can use Markdown or restructuredText to format your comment.

links

social