From 27be5bc72855a0fbbdae230bc144624c9eb85f5e Mon Sep 17 00:00:00 2001 From: Michiel Van Der Kolk Date: Thu, 17 Mar 2005 20:50:03 +0000 Subject: Initial check in dumb 0.9.2 - has a few usages of floating point that should be rewritten to fixed point. seems to compile cleanly for iriver. git-svn-id: svn://svn.rockbox.org/rockbox/trunk@6197 a1c6a512-1295-4272-9138-f99709370657 --- apps/codecs/dumb/docs/ptr.txt | 129 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 apps/codecs/dumb/docs/ptr.txt (limited to 'apps/codecs/dumb/docs/ptr.txt') diff --git a/apps/codecs/dumb/docs/ptr.txt b/apps/codecs/dumb/docs/ptr.txt new file mode 100644 index 0000000000..0eb42ccf02 --- /dev/null +++ b/apps/codecs/dumb/docs/ptr.txt @@ -0,0 +1,129 @@ +/* _______ ____ __ ___ ___ + * \ _ \ \ / \ / \ \ / / ' ' ' + * | | \ \ | | || | \/ | . . + * | | | | | | || ||\ /| | + * | | | | | | || || \/ | | ' ' ' + * | | | | | | || || | | . . + * | |_/ / \ \__// || | | + * /_______/ynamic \____/niversal /__\ /____\usic /| . . ibliotheque + * / \ + * / . \ + * ptr.txt - Pointer explanation. / / \ \ + * | < / \_ + * | \/ /\ / + * \_ / > / + * | \ / / + * | ' / + * \__/ + */ + + +A pointer is a small variable (often the same size as an int BUT NOT ALWAYS) +that holds the address of something in memory. You create a pointer by adding +a * to a variable, as follows: + + int x, *y; + + x = 5; + y = &x; + +The & means 'address of', so &x gives us a pointer to x. We are storing it in +y. + + (*y)++; + +The * here means 'value at'. It's known as the 'dereferencing' operator. When +written before a pointer, as it is here, it allows you to treat the value +like a normal variable. In this case we are incrementing the value. If we +look at x, we'll find that it now contains 6, not 5. + + y++; + +Here we are incrementing the pointer itself. This is useful for traversing +through an array, but in this particular example it is not much use. + + *y++; + +Beware; this will increment the pointer, not the value stored there. It will +return the value stored at the pointer (before incrementing the pointer), so +you can use this in a bigger expression. This is why we needed brackets in +the first example. + +Note that you will not need these three examples when working with DUMB; they +are simply to help illustrate the idea of pointers. + +Also be aware that when defining pointers you attach the * to the variable, +not to the type. The following example will create a pointer and an int, not +two pointers: + + int *a, b; + +That is why I believe it's a good idea to put a space before the * and not +after it, although programmers are divided on this. + + y = 0; + y = NULL; + +These two statements are equivalent. 0, or NULL, is a special value that is +guaranteed to have a different value from any valid pointer. This is most +often used to indicate that something doesn't point anywhere. DUMB's +functions may return it on occasion. However, in simple usage of DUMB, you +will not actually need to check for it. + +Some of DUMB's functions return pointers to structs. (A struct is an +aggregration of other variables, such as ints, pointers, or other structs. +You can generally treat a struct as a single unit.) Here's an example of such +a function: + + DUH *dumb_load_it(const char *filename); + +You do not know what the DUH struct actually contains; dumb.h and aldumb.h +only give the compiler enough information to deal with pointers to them. DUMB +will take charge of everything that happens inside a DUH struct. + +The above function will create a DUH struct for you. First it allocates +the memory it needs, then it fills the struct with data, then it returns a +pointer. This DUH struct will contain the data necessary to play an IT file. +You can define a suitable variable and store the pointer in it as follows: + + DUH *duh = dumb_load_it("music.it"); + +Or this can be split up: + + DUH *duh; + duh = dumb_load_it("music.it"); + +In order to use this DUH struct later, you must pass its pointer to other +functions. To pass the pointer to a function, simply write 'duh' for the +appropriate parameter. + +When you've finished with a DUH struct (this applies equally to the other +structs DUMB deals with), you must pass it to an appropriate function for +freeing up the memory: + + unload_duh(duh); + +After you've done this, the memory will no longer be allocated, and the +pointer will have no meaning. You may wish to set it to NULL at this point +for safety. Alternatively just be sure not to use the present value of the +pointer any more. You can of course assign a new value to the pointer, e.g. +by calling dumb_load_it() again. + +Note the following: + + DUH *duh2 = duh; + +This only duplicates the pointer, not the DUH itself. You still only have one +copy of the DUH. There is no way of duplicating a DUH, short of loading it +twice. This is not a problem, because DUMB can play it 'twice at the same +time' anyway. + +That should be all you need to know about pointers in order to use DUMB. If +there's anything you feel should be explained better here, or anything else +that should be added, please don't hesitate to let me know! + + +Ben Davis +entheh@users.sf.net +IRC EFnet #dumb +See readme.txt for details on using IRC. -- cgit v1.2.3