mirror of
https://github.com/JetSetIlly/Gopher2600.git
synced 2025-04-02 11:02:17 -04:00
130 lines
4.9 KiB
Go
130 lines
4.9 KiB
Go
// This file is part of Gopher2600.
|
|
//
|
|
// Gopher2600 is free software: you can redistribute it and/or modify
|
|
// it under the terms of the gnu general public license as published by
|
|
// the Free Software Foundation, either version 3 of the License, or
|
|
// (at your option) any later version.
|
|
//
|
|
// Gopher2600 is distributed in the hope that it will be useful,
|
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
// GNU General Public License for more details.
|
|
//
|
|
// You should have received a copy of the GNU General Public License
|
|
// along with Gopher2600. If not, see <https://www.gnu.org/licenses/>.
|
|
|
|
// Package cartridgeloader is used to specify the cartridge data that is to be
|
|
// attached to the emulated VCS.
|
|
//
|
|
// When the cartridge is ready to be loaded into the emulator, the Load()
|
|
// function should be used. The Load() function handles loading of data from a
|
|
// different sources. Currently on local-file and data over HTTP is supported.
|
|
//
|
|
// As well as the filename, the Loader type allows the cartridge mapping to be
|
|
// specified, if required. The simplest instantiation therefore is:
|
|
//
|
|
// cl := cartridgeloader.Loader{
|
|
// Filename: "roms/Pitfall.bin",
|
|
// }
|
|
//
|
|
// It is stronly preferred however, that the NewLoader() function is used to
|
|
// initialise the Loader or important fields risk being initialised
|
|
// incorrectly.
|
|
//
|
|
// The NewLoader() function accepts two arguments. The filename of the
|
|
// cartridge (which might be a HTTP url) and the cartridge mapper. In most
|
|
// cases the mapper will be "AUTO" to indicate that we don't know (or
|
|
// particular care) what the mapping format is.
|
|
//
|
|
// # File Extensions
|
|
//
|
|
// The file extension of a file will specify the cartridge mapping and will
|
|
// cause the emulation to use that mapping. Most 2600 ROM files have the
|
|
// extension "bin" but sometimes it is necessary to specify explicitly what
|
|
// the mapper is.
|
|
//
|
|
// The following quoted file extensions are recognised (case insenstive):
|
|
//
|
|
// 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"
|
|
// DF "DF"
|
|
// 3E "3E"
|
|
// 3E+ "3E+"
|
|
// Superbank "SB"
|
|
// DPC (Pitfall2) "DPC"
|
|
// DPC+ "DP+"
|
|
// CDF "CDF" (including CDFJ)
|
|
//
|
|
// In addition to these above there a three "special" mapping formats. Which
|
|
// aren't really mappers in the normal sense but which will none-the-less
|
|
// trigger a particular cartridge emulation path.
|
|
//
|
|
// "MP3" and "WAV" indicate that the emulation should use the Supercharger
|
|
// mapper but with the understanding that the data will be loaded from audio
|
|
// data.
|
|
//
|
|
// "MVC" indicates that the data is a MovieCart stream. Because of the
|
|
// potential size of these files, data is streamed from the file. Also,
|
|
// steaming over HTTP is not yet currently supported.
|
|
//
|
|
// Finally a file extension of "BIN", "ROM", "A26" will tell the mapping system
|
|
// to "fingerprint" the cartridge data to ascertain the mapping type.
|
|
//
|
|
// Fingerprinting is not handled by the cartridlgeloader package.
|
|
//
|
|
// # Hash
|
|
//
|
|
// The Hash field of the Loader type contains the SHA1 value of the loaded
|
|
// data. It is valid after the Load() function has completed successfully. If
|
|
// the field is not empty before Load() is called, that value will be compared
|
|
// with the calculated value. An error is returned if the values differ.
|
|
//
|
|
// In most cases you wouldn't want to change the Hash field before calling the
|
|
// Load() function but it is sometimes useful to make sure the correct file is
|
|
// being loaded - for example the recorder package uses it to help make sure
|
|
// playback is correct.
|
|
//
|
|
// The hash value is invalid/unused in the case of streamed data
|
|
//
|
|
// # Streaming
|
|
//
|
|
// For some cartridge types it is necessary to stream bytes from the file
|
|
// rather than load them all at once. For these types of cartridges the Load()
|
|
// function will open a stream and readbable via the StreamedData field.
|
|
//
|
|
// The function IsStreaming() returns true if data is to be read from the
|
|
// StreamedData field rather than the Data field.
|
|
//
|
|
// For streaming to work NewLoader() must have been used to instantiate the
|
|
// Loader type.
|
|
//
|
|
// # Closing
|
|
//
|
|
// Instances of Loader must be closed with Close() when it is no longer
|
|
// required.
|
|
//
|
|
// # OnInserted
|
|
//
|
|
// The OnInserted field is used by some cartridges to indicate when the
|
|
// cartridge data has been loaded into memory and something else needs to
|
|
// happen that is outside of the scope of the cartridge package. Currently,
|
|
// this is used by the Supercharder and PlusROM.
|
|
//
|
|
// # Notification Hook
|
|
//
|
|
// Some cartridge mappers will generate notifications (see notification.Notify type). The
|
|
// NotifcationHook can be specified in order to respond to those events.
|
|
package cartridgeloader
|