Documentation
¶
Overview ¶
Package cartridgeloader is used to load cartridge data so that it can be used with the cartridge pacakage
File Extensions ¶
The file extension of a file will specify the cartridge mapping and will cause the emulation to use that mapping.
The following file extensions are recognised and force the use of the specified mapper:
Atari 2k "2k" Atari 4k "4k" Atari 8k "F8" Atari 16k "F6" Atari 32k "F4" Atari 2k (RAM) "2k+" Atari 4k (RAM) "4k+" Atari 8k (RAM) "F8+" Atari 16k (RAM) "F6+" Atari 32k (RAM) "F4+" CBS "FA" Parker Bros "E0" M-Network "E7" Tigervision "3F" Supercharger "AR", "MP3, "WAV" DF "DF" 3E "3E" 3E+ "3E+" Superbank "SB" DPC (Pitfall2) "DPC" DPC+ "DP+" CDF "CDF" (including CDFJ) MovieCart "MVC"
File extensions are case insensitive.
A file extension of "BIN", "ROM", "A26" indicates that the data should be fingerprinted as normal.
Preloaded data ¶
Cartridges with lots of data wil be streamed off disk as required. For example, Moviecart or Supercharge audio tapes can be large and don't need to exist in memory for a very long time.
However, for practical reasons the first 1MB of data of any file will be 'preloaded'. When reading cartridge data you don't need to worry about whether data has been preloaded or not, except that it does affect both hashing and fingerprinting.
Hashes ¶
The creation of a cartridge loader includes the creation of both a SHA1 and an MD5 hash. Hashes are useful for matching cartridges regardless of path or filename
The data used to create the hash is limited to the data that has been preloaded (see above).
Fingerprinting ¶
Cartridge data can be checked for 'fingerprint' data that can be used to decide on the 'mapping' the cartridge uses. The three cartridge loader functions, Contains(), ContainsLimit() and Count() can be used to search the preloaded data (see above) for specific bytes sequences.
More complex fingerprinting can be done with the Read() function. However, because the Read() function works with the complete cartridge and not just the preloaded data, care should be taken not to read too much of the data for reasons of computation time. The constant value FingerprintLimit is provided as a useful value to which a Read() loop can be limited.
Once fingerprinting has been completed it is very important to remember to reset the Read() position with the Seek() command:
cartridgeloader.Seek(0, io.SeekStart)
Index ¶
- Constants
- Variables
- func NameFromFilename(filename string) string
- type Loader
- func (ld *Loader) Close() error
- func (ld Loader) Contains(subslice []byte) bool
- func (ld Loader) ContainsLimit(limit int, subslice []byte) bool
- func (ld Loader) Count(subslice []byte) int
- func (ld Loader) Read(p []byte) (int, error)
- func (ld *Loader) Reload() error
- func (ld *Loader) Reset() error
- func (ld Loader) Seek(offset int64, whence int) (int64, error)
- func (ld Loader) Size() int
Constants ¶
const FingerprintLimit = 65536
Fingerprinting beyond the first 64k or so of cartridge data can result in very slow fingerprinting, particular if looking at a large file that is not a cartridge file at all
The 64k value is arbitary but in practice it's a sufficiently large value and any data beyond that limit is unlikely to reveal anything of worth
Variables ¶
var FileExtensions = []string{}
FileExtensions is the list of file extensions that are recognised as being indications of cartridge data
var NoFilename = errors.New("no filename")
sentinal error for when it is attempted to create a loader with no filename
Functions ¶
func NameFromFilename ¶ added in v0.30.0
NameFromFilename converts a filename to a shortened version suitable for display. Useful in some contexts where creating a cartridge loader instance is inconvenient.
Types ¶
type Loader ¶
type Loader struct {
io.ReadSeeker
// the name to use for the cartridge. in the case of embedded data the name
// will be the name provided to the NewLoaderFromData() function
Name string
// filename of cartridge being loaded. this is the absolute path that was
// used to load the cartridge
//
// in the case of embedded data the filename will be the name provided to
// the NewLoaderFromData() function
//
// use of the Filename can be useful, for example, for checking if the TV
// specification is indicated
Filename string
// empty string or "AUTO" indicates automatic fingerprinting
Mapping string
// hashes of data
HashSHA1 string
HashMD5 string
// does the Data field consist of sound (PCM) data
IsSoundData bool
// contains filtered or unexported fields
}
Loader abstracts all the ways data can be loaded into the emulation.
func NewLoaderFromData ¶ added in v0.30.0
NewLoaderFromData is the preferred method of initialisation for the Loader type when loading data from a byte array. It's a great way of loading embedded data (using go:embed) into the emulator.
The mapping argument should indicate the format of the data or "AUTO" to indicate that the emulator can perform a fingerprint.
The name argument should not include a file extension because it won't be used.
func NewLoaderFromFilename ¶ added in v0.30.0
NewLoaderFromFilename is the preferred method of initialisation for the Loader type when loading data from a filename.
The mapping argument will be used to set the Mapping field, unless the argument is either "AUTO" or the empty string. In which case the file extension is used to set the field.
File extensions should be the same as the ID of the intended mapper, as defined in the cartridge package. The exception is the DPC+ format which requires the file extension "DP+"
File extensions ".BIN" and "A26" will set the Mapping field to "AUTO".
Alphabetic characters in file extensions can be in upper or lower case or a mixture of both.
Filenames can contain whitespace, including leading and trailing whitespace, but cannot consist only of whitespace.
func (*Loader) Close ¶ added in v0.10.1
Implements the io.Closer interface.
Should be called before disposing of a Loader instance.
func (Loader) Contains ¶ added in v0.30.0
Contains returns true if subslice appears anywhere in the preload data.
func (Loader) ContainsLimit ¶ added in v0.30.0
ContainsLimit returns true if subslice appears anywhere in the preload data and within the byte limit value supplied as a fuction parameter.
func (Loader) Count ¶ added in v0.30.0
Count returns the number of non-overlapping instances of subslice in the preload data.
func (*Loader) Reset ¶ added in v0.30.0
Reset prepares the loader for fresh reading. Useful to call after data has been Read() or if you need to make absolutely sure subsequent calls to Read() start from the beginning of the data stream
Source Files