view release on metacpan or  search on metacpan

SID.pm  view on Meta::CPAN

B<Usage:>

B<$OBJECT>->B<write>(SCALAR) or
B<$OBJECT>->B<write>('-filename' => SCALAR) or
B<$OBJECT>->B<write>(FILEHANDLE) or
B<$OBJECT>->B<write>('-filehandle' => FILEHANDLE)

Writes the SID file given by the filename SCALAR or by FILEHANDLE to disk. If
neither SCALAR nor FILEHANDLE is specified (with or without a name-value
pair), the value of I<FILENAME> is used to determine the name of the output
file. If that is not set, either, B<write>() returns an undef. Note that
SCALAR and FILEHANDLE here can be different than the value of I<FILENAME>! If
SCALAR is defined, it will not overwrite the filename stored in I<FILENAME>.

I<write> will create a version 1 or version 2/2NG/3/4 SID file depending on the
value of the I<version> field, and an RSID file if the I<magicID> is set to
'RSID', regardless of whether the other fields are set correctly or not, or
even whether they are undef'd or not. However, if
$OBJECT->I<alwaysValidateWrite>(1) was called beforehand, I<write> will always
write a validated PSID or RSID SID file. See I<validate>.

=item B<$OBJECT>->B<get>([SCALAR])

Retrieves the value of the SID field given by the name SCALAR, or returns a
hash of all the recognized SID fields with their values if called in an
array/hash context.

If the fieldname given by SCALAR is unrecognized, the operation is ignored
and an undef is returned. If SCALAR is not specified and I<get> is not called
from an array context, the same terrible thing will happen. So try not to do
either of these.

For backwards compatibility reasons, "copyright" is always accepted as an
alias for the "released" fieldname and "name" is always accepted as an
alias for "title".

=item B<$OBJECT>->B<getFileName>()

Returns the current I<FILENAME> stored in the object.

=item B<$OBJECT>->B<getFileSize>()

Returns the total size of the SID file that would be written by
$OBJECT->I<write>() if it was called right now. This means that if you read in
a version 1 file and changed the I<version> field to 2+ without actually
saving the file, the size returned here will reflect the size of how big the
version 2+ file would be.

=item B<$OBJECT>->B<getRealLoadAddress>()

The "real load address" indicates what is the actual Commodore-64 memory
location where the SID data is going to be loaded into. If I<loadAddress> is
non-zero, then I<loadAddress> is returned here, otherwise it's the first two
bytes of I<data> (read from there in little-endian format).

=item B<$OBJECT>->B<getSpeed>([SCALAR])

Returns the speed of the song number specified by SCALAR. If no SCALAR is
specified, returns the speed of song #1. Speed can be either 0 (indicating a
vertical blank interrupt (50Hz PAL, 60Hz NTSC)), or 1 (indicating CIA 1 timer
interrupt (default is 60Hz)).

For PlaySID specific files the corresponding bit of I<speed> from SCALAR modulo
32 is returned ("wraparound" behavior for songs > 32).

For all other files if SCALAR > 32, then bit #31 (MSB) of the I<speed> field is
returned ("pegged at 32" behavior for songs > 32).

=item B<$OBJECT>->B<getMUSPlayer>()

Returns the value of the 'MUSPlayer' bit of the I<flags> field if I<flags> is
specified (i.e. when I<version> is 2+), or undef otherwise. The returned value
is either 0 (indicating a built-in music player) or 1 (indicating that I<data>
is a Compute!'s Sidplayer MUS data and the music player must be merged).

=item B<$OBJECT>->B<isMUSPlayerRequired>()

This is an alias for $OBJECT->I<getMUSPlayer>().

=item B<$OBJECT>->B<getPlaySID>()

Returns the value of the 'psidSpecific' bit of the I<flags> field if I<flags>
is specified (i.e. when I<version> is 2+) and the I<magicID> is 'PSID';
returns 1 if I<version> is 1; undef otherwise. The returned value is either 0
(indicating that I<data> is Commodore-64 compatible) or 1 (indicating that
I<data> is PlaySID specific).

=item B<$OBJECT>->B<isPlaySIDSpecific>()

This is an alias for $OBJECT->I<getPlaySID>().

=item B<$OBJECT>->B<isRSID>()

Returns 'true' if the I<magicID> is 'RSID', 'false' otherwise.

=item B<$OBJECT>->B<getC64BASIC>()

Returns the value of the 'C64BASIC' bit of the I<flags> field if I<flags>
is specified (i.e. when I<version> is 2+) and the I<magicID> is 'RSID', or
undef otherwise. The returned value is either 1 (indicating that I<data>
has a BASIC executable portion, or 0 otherwise.

=item B<$OBJECT>->B<isC64BASIC>()

This is an alias for $OBJECT->I<getC64BASIC>().

=item B<$OBJECT>->B<getClock>()

Returns the value of the 'clock' (video standard) bits of the I<flags> field
if I<flags> is specified (i.e. when I<version> is 2+), or undef otherwise. The
returned value is one of 0 (UNKNOWN), 1 (PAL), 2 (NTSC) or 3 (EITHER).

=item B<$OBJECT>->B<getClockByName>()

Returns the textual value of the 'clock' (video standard) bits of the I<flags>
field if I<flags> is specified (i.e. when I<version> is 2+), or undef
otherwise. The textual value will be one of UNKNOWN, PAL, NTSC or EITHER.

=item B<$OBJECT>->B<getSIDModel>([SCALAR])

SID.pm  view on Meta::CPAN

Given one or more field-value pairs it changes the SID fields given by
I<field> to have I<value>.

If you try to set a field that is unrecognized, that particular field-value
pair will be ignored. Trying to set the I<version> field to anything other
than 1, 2, 3 or 4, the invalid value will be ignored. The same is true for the
I<magicID> field if you try to set it to anything else but 'PSID' or 'RSID'.

Whenever the version number is changed to 1, the I<flags>, I<startPage>,
I<pageLength> and I<reserved> fields are automatically set to be undef'd, the
I<magicID> is set to 'PSID' and the I<dataOffset> field is set to 0x0076.

Whenever the version number is changed to 2, the I<flags>, I<startPage>,
I<pageLength> and I<reserved> fields are zeroed out if they are not set, yet.
If the version number is changed to 3, the I<secondSIDAddress> field will also
be set to 0. If the version number is changed to 4, the I<thirdSIDAddress>
field will also be set to 0 and I<reserved> will be set to undef.

Whenever the I<magicID> is changed from 'RSID' to 'PSID' or vice versa and
I<flags> is not specified at the same time, the I<psidSpecific> field for
PSID or the I<C64BASIC> field for RSID is set to 0.

Whenever the I<magicID> is set to 'RSID', the I<loadAddress>, I<playAddress>
and I<speed> fields are set to 0, plus the 'psidspecific' bit in the I<flags>
field is also set to 0. If I<loadAddress> was non-zero before, its value is
prepended to I<data>.

If you try to set I<magicID>, I<flags>, I<startPage>, I<pageLength> or
I<reserved> when I<version> is not 2+, the values will be ignored. Trying to
set I<dataOffset> when I<version> is 1 will always reset its value to 0x0076,
and I<dataOffset> can't be set to lower than 0x007C if I<version> is 2+. You
can set it higher, though, in which case either the relevant portion of the
original extra padding bytes between the SID header and the I<data> will be
preserved, or additional 0x00 bytes will be added between the SID header and
the I<data> if necessary.

Note that the textual fields (I<title>, I<author>, or I<released>) will
always be converted to ISO 8859-1 ASCII encoding (i.e. single byte ASCII
chars), even if they were Unicode to begin with. This might result in some
Unicode characters without ASCII equivalents getting changed to a
question mark ('?').

For backwards compatibility reasons, "copyright" is always accepted as an
alias for the "released" fieldname and "name" is always accepted as an
alias for "title".

=item B<$OBJECT>->B<setFileName>(SCALAR)

Sets the I<FILENAME> to SCALAR. This filename is used by $OBJECT->I<read>()
and $OBJECT->I<write>() when either one of them is called without any
arguments. SCALAR can specify either a relative or an absolute pathname to the
file - in fact, it can be anything that can be passed to a B<FileHandle>
type object as a filename.

=item B<$OBJECT>->B<setSpeed>(SCALAR1, SCALAR2)

Changes the speed of the song number specified by SCALAR1 to that of SCALAR2.
SCALAR1 has to be more than 1 and less than the value of the I<songs> field.
SCALAR2 can be either 0 (indicating a vertical blank interrupt (50Hz PAL, 60Hz
NTSC)), or 1 (indicating CIA 1 timer interrupt (default is 60Hz)). An undef is
returned if neither was specified.

For PlaySID specific files if SCALAR1 is greater than 32, the SCALAR1 module 32
bit of the I<speed> field will be set, overwriting whatever value was in that
bit before ("wraparound" behavior for songs > 32).

For all other files if SCALAR1 is greater than 32, then bit #31 (MSB) of the
I<speed> flag will be set, overwriting whatever value was in that bit before
("pegged at 32" behavior for songs > 32).

=item B<$OBJECT>->B<setMUSPlayer>(SCALAR)

Changes the value of the 'MUSPlayer' bit of the I<flags> field to SCALAR if
I<flags> is specified (i.e. when I<version> is 2+), returns an undef otherwise.
SCALAR must be either 0 (indicating a built-in music player) or 1 (indicating
that I<data> is a Compute!'s Sidplayer MUS data and the music player must be
merged).

=item B<$OBJECT>->B<setPlaySID>(SCALAR)

Changes the value of the 'psidSpecific' bit of the I<flags> field to SCALAR if
I<flags> is specified (i.e. when I<version> is 2+) and the I<magicID> is 'PSID',
returns an undef otherwise. SCALAR must be either 0 (indicating that I<data>
is Commodore-64 compatible) or 1 (indicating that I<data> is PlaySID specific).

Note that it is not possible to set v1 files to be PlaySID specific - it's
implied that all v1 files are PlaySID specific.

=item B<$OBJECT>->B<setC64BASIC>(SCALAR)

Changes the value of the 'C64BASIC' bit of the I<flags> field to SCALAR if
I<flags> is specified (i.e. when I<version> is 2+) and the I<magicID> is 'RSID',
returns an undef otherwise. SCALAR must be either 1 (indicating that I<data>
has a C64 BASIC executable portion) or 0 otherwise. Setting this flag to 1
also sets the I<initAddress> field to 0.

=item B<$OBJECT>->B<setClock>(SCALAR)

Changes the value of the 'clock' (video standard) bits of the I<flags> field
to SCALAR if I<flags> is specified (i.e. when I<version> is 2+), returns an
undef otherwise. SCALAR must be one of 0 (UNKNOWN), 1 (PAL), 2 (NTSC) or 3
(EITHER).

=item B<$OBJECT>->B<setClockByName>(SCALAR)

Changes the value of the 'clock' (video standard) bits of the I<flags> field
if I<flags> is specified (i.e. when I<version> is 2+), returns an undef
otherwise. SCALAR must be be one of UNKNOWN, NONE, NEITHER (all 3 indicating
UNKNOWN), PAL, NTSC or ANY, BOTH, EITHER (all 3 indicating EITHER) and is
case-insensitive.

=item B<$OBJECT>->B<setSIDModel>(SCALAR1, [SCALAR2])

Changes the value of the 'sidModel' bits of the I<flags> field if I<flags> is
specified (i.e. when I<version> is 2+), returns an undef otherwise. SCALAR1
must be one of 0 (UNKNOWN), 1 (6581), 2 (8580) or 3 (EITHER).

If SCALAR2 is defined and it's 1, it behaves as above. If SCALAR2 is 2 and
I<version> is 3 or larger, it sets the 'sidModel' bits of the I<flags> field
for the second SID, returns an undef otherwise. If SCALAR2 is 3 and I<version>