The implementation of the %pagebuffer% device. More...

#include "skinkit.h"
#include "kit.h"
#include "kitdevs.h"
#include "mem.h"
#include "file.h"
#include "swdevice.h"
#include "swdataapi.h"
#include "apis.h"
#include "swraster.h"
#include "skindevs.h"
#include "devutils.h"
#include "swoften.h"
#include "zlibutil.h"
#include "devparam.h"
#include "skinmon.h"
#include "ktime.h"
#include "swevents.h"
#include "swtimelines.h"
#include "rasterstoreapi.h"
#include "hqmemcpy.h"
#include "hqmemset.h"
#include "rasthand.h"
#include "rdrerrors.h"
#include "scrndev.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>

Data Structures
struct	PGBDescription
	The PGBDescription structure contains the per-pass rendering information, including a RasterDescription, which is the part exported to the raster callback, and some local fields for keeping track of partial paints. More...

struct	PGBPrivate
	Private data for PGB device. More...

struct	PageBufferInParameters
	The following structures will hold all of the device parameters. More...

Macros
#define	MAX_MEMORY_CACHE_SIZE_KBYTES (512) /* 512K */
	An arbitrarily chosen default maximum size for the in-memory band cache. When this much memory is used by compressed band data, the band data is flushed to disk. This is used to initialise the PGB parameter "MaxBandCacheKiB", which is used to limit the band cache size.

#define	MAX_PARAMS NUM_ARRAY_ITEMS(devparams)
	Number of parameters in devparams array.

#define	PARAM_IS_SET(_index_) ((devparams[_index_].flags & PARAM_SET) != 0)
	Test whether a parameter has been set.

Functions
void	SwLePgbDebugChecksumRasters (HqBool print)
	Set a flag determining if the pagebuffer device should calculate and print checksums for rasters. More...

static HqnResult	storeBandInCache (PGBPrivate priv, uint8 pBuff, uint32 length)
	Store bytes in the PGB store. More...

static HqnResult	getBand (PGBPrivate priv, uint8 pBuff, uint32 length)
	Read the band described by the state of a PGBDescription into a buffer, either from memory or from disk. This is the highest level getter function for bands. More...

static HqBool	KInitializePGBDescription (PGBPrivate priv, sw_datum raster_params, RASTER_LAYOUT raster_layout, int32 sheet_index, PGBDescription pgb)
	Initialize a PGBDescription struct. More...

static void	KFreePGBDescription (PGBDescription *pgb)
	Destructor function for PGBDescription structs. More...

HqBool	SwLePgbSetCallback (const char name, int32 type, SwLeParamCallback pfnPGBCallback)
	Sets a callback functions for the named pagebuffer device parameter. More...

static sw_event_result	pgb_tl_start (void context, sw_event ev)

static int32	pgb_ioerror (DEVICELIST *dev)
	The ioerror routine for the pagebuffer device type.

static int32	pgb_noerror (DEVICELIST *dev)
	The noerror routine for the pagebuffer device type.

static void *	pgb_void (DEVICELIST *dev)
	The void routine for the pagebuffer device type.

static int32	pgb_init_device (DEVICELIST *dev)
	The init_device routine for the pagebuffer device type. More...

static DEVICE_FILEDESCRIPTOR	pgb_open_file (DEVICELIST dev, uint8 filename, int32 openflags)
	The open_file routine for the pagebuffer device type.

static int32	pgb_read_file (DEVICELIST dev, DEVICE_FILEDESCRIPTOR descriptor, uint8 buff, int32 len)
	The read_file routine for the pagebuffer device type.

static int32	pgb_write_file (DEVICELIST dev, DEVICE_FILEDESCRIPTOR descriptor, uint8 buff, int32 len)
	The write_file routine for the pagebuffer device type.

static int32	pgb_close_file (DEVICELIST *dev, DEVICE_FILEDESCRIPTOR descriptor)
	The close_file routine for the pagebuffer device type. More...

static int32	pgb_abort_file (DEVICELIST *dev, DEVICE_FILEDESCRIPTOR descriptor)
	The abort_file function for the pagebuffer device type. More...

static int32	pgb_seek_file (DEVICELIST dev, DEVICE_FILEDESCRIPTOR descriptor, Hq32x2 destination, int32 whence)
	The seek_file routine for the pagebuffer device type. More...

static int32	pgb_bytes_file (DEVICELIST dev, DEVICE_FILEDESCRIPTOR descriptor, Hq32x2 bytes, int32 reason)
	The bytes_file routine for the pagebuffer device type.

static int32	pgb_status_file (DEVICELIST dev, uint8 filename, STAT *statbuff)
	The status_file routine for the pagebuffer device type.

static void *	pgb_start_file_list (DEVICELIST dev, uint8 pattern)
	The start_file_list routine for the pagebuffer device type.

static int32	pgb_next_file (DEVICELIST dev, void handle, uint8 pattern, FILEENTRY *entry)
	The next_file routine for the pagebuffer device type.

static int32	pgb_end_file_list (DEVICELIST dev, void handle)
	The end_file_list routine for the pagebuffer device type.

static int32	pgb_rename_file (DEVICELIST dev, uint8 file1, uint8 *file2)
	The rename_file routine for the pagebuffer device type.

static int32	pgb_delete_file (DEVICELIST dev, uint8 filename)
	The delete_file routine for the pagebuffer device type. It closes and destroys an in-memory or disk-based cache of PGB data that was created in earlier calls to the device.

static int32	pgb_set_param (DEVICELIST dev, DEVICEPARAM param)
	The set_param function for the pagebuffer device type. More...

static int32	pgb_status_device (DEVICELIST dev, DEVSTAT devstat)
	The status_device function for the pagebuffer device type. More...

Detailed Description

The implementation of the %pagebuffer% device.

This device is the medium for delivering the output raster data from the RIP core to the skin.

Note: You should not modify this code. This file and the interface between it and the RIP core are deprecated and will be withdrawn in a future release.

Function Documentation

◆ getBand()

static HqnResult getBand	(	PGBPrivate *	priv,
		uint8 *	pBuff,
		uint32	length
	)

static

Read the band described by the state of a PGBDescription into a buffer, either from memory or from disk. This is the highest level getter function for bands.

Parameters

[in]	priv	The PGB device private data.
[out]	pBuff	The buffer into which the band data is read. This must be allocated by the caller – ultimately the RIP itself.
[in,out]	length	Expected length of the decompressed data.

Returns: 0 on success; a monitor UID error otherwise.

◆ KFreePGBDescription()

static void KFreePGBDescription ( PGBDescription * pgb )

static

Destructor function for PGBDescription structs.

Parameters

[in] pgb Pointer to the PGB to be freed.

◆ KInitializePGBDescription()

static HqBool KInitializePGBDescription	(	PGBPrivate *	priv,
		sw_datum *	raster_params,
		RASTER_LAYOUT *	raster_layout,
		int32	sheet_index,
		PGBDescription *	pgb
	)

static

Initialize a PGBDescription struct.

Returns: TRUE on success; FALSE otherwise.

◆ pgb_abort_file()

static int32 pgb_abort_file	(	DEVICELIST *	dev,
		DEVICE_FILEDESCRIPTOR	descriptor
	)

static

The abort_file function for the pagebuffer device type.

This function will be called in place of close_file when an error is reported during rendering which causes rendering to be abandoned.

◆ pgb_close_file()

static int32 pgb_close_file	(	DEVICELIST *	dev,
		DEVICE_FILEDESCRIPTOR	descriptor
	)

static

The close_file routine for the pagebuffer device type.

Note that this function may be called multiple times on the same page if partial painting is invoked.

◆ pgb_init_device()

static int32 pgb_init_device ( DEVICELIST * dev )

static

The init_device routine for the pagebuffer device type.

In this example, it is required to fill in the parameter name lengths, which we cannot conveniently initialize statically.

◆ pgb_seek_file()

static int32 pgb_seek_file	(	DEVICELIST *	dev,
		DEVICE_FILEDESCRIPTOR	descriptor,
		Hq32x2 *	destination,
		int32	whence
	)

static

The seek_file routine for the pagebuffer device type.

This function is required.

The seek is to the first line of a band. The PGB parameter BandLines indicates how many lines are in this band.

◆ pgb_set_param()

static int32 pgb_set_param	(	DEVICELIST *	dev,
		DEVICEPARAM *	param
	)

static

The set_param function for the pagebuffer device type.

This implementation uses the structures defined at the head of the file to record the parameters.

This is done by a simple search on the name. However, given the very large number of parameters it would be more efficient to use a hashing technique or a binary chop on a table organised alphabetically or something of the kind.

◆ pgb_status_device()

static int32 pgb_status_device	(	DEVICELIST *	dev,
		DEVSTAT *	devstat
	)

static

The status_device function for the pagebuffer device type.

This function has a rather specialized interpretation for the pagebuffer device. It can be used to give more memory to the rip in which it can render: either a whole page's worth (and we know from the pgbparams structure how big that is going to be) to operate as a frame device, or any spare memory so that it can get further ahead of the real printer if it has time to do so.

In this example, we supply no additional memory.

◆ pgb_tl_start()

static sw_event_result pgb_tl_start	(	void *	context,
		sw_event *	ev
	)

static

Handler to capture PGB device timelines, to use as file descriptor and owner for band handled messages, and skin job timeline, for extracting the skin's Job ID.

◆ storeBandInCache()

static HqnResult storeBandInCache	(	PGBPrivate *	priv,
		uint8 *	pBuff,
		uint32	length
	)

static

Store bytes in the PGB store.

Parameters

[in]	priv	The PGB device private data.
[in]	pBuff	The buffer containing the bytes to be stored.
[in]	length	The number of bytes to read from pBuff.

Returns: 0 if store succeeded; an error UID otherwise.

◆ SwLePgbDebugChecksumRasters()

void SwLePgbDebugChecksumRasters ( HqBool print )

Set a flag determining if the pagebuffer device should calculate and print checksums for rasters.

Parameters

print TRUE if checksums should be printed, FALSE if they should not be printed.

This is a debug function, and will not have effect in release versions of the RIP.

◆ SwLePgbSetCallback()

HqBool SwLePgbSetCallback	(	const char *	paramname,
		int32	paramtype,
		SwLeParamCallback *	pfnPGBCallback
	)

Sets a callback functions for the named pagebuffer device parameter.

If a callback function is registered correctly, it will be called whenever the value of the pagebuffer device parameter is changed. There is exactly one callback for each parameter; setting the callback will override the previous callback definition. To remove a callback hook, call this function with a NULL function pointer.

Parameters

paramname	The parameter name to monitor.
paramtype	The type of the parameter name to monitor. The callback functions use a generic pointer to pass the changed parameter value. Passing the expected type in with the hook function lets the skinkit check that the hook function will be passed the type it expects.
pfnPGBCallback	Pointer to a function though which the RIP informs the skin of pagebuffer type changes. The skin may call SwLeSetRasterAPI() in this routine, to route callbacks to different backends.

Return values

FALSE	If the callback could not be set (either the name or type of the PGB param is incorrect).
TRUE	If the callback was set.

Data Structures

Macros

Functions

Detailed Description

Function Documentation

◆ getBand()

◆ KFreePGBDescription()

◆ KInitializePGBDescription()

◆ pgb_abort_file()

◆ pgb_close_file()

◆ pgb_init_device()

◆ pgb_seek_file()

◆ pgb_set_param()

◆ pgb_status_device()

◆ pgb_tl_start()

◆ storeBandInCache()

◆ SwLePgbDebugChecksumRasters()

◆ SwLePgbSetCallback()